How MemIndex works

MemIndex keeps useful context between agent sessions. It saves what changed, why you made a choice, and what you tried. Your next session has somewhere to start.

From work to memory

1. Your agent's integration sends session activity to MemIndex. Depending on the agent, this comes from session events or its saved conversation files.
2. MemIndex asks your chosen model service to turn that activity into short notes. It also writes session summaries.
3. Notes are saved with their project and session.
4. Supported integrations bring project context into later sessions. The agent can also search for older work when it needs it.

These notes are generated by a model. Check the source before relying on a note for an important decision.

Find the useful part

The local memory tools let an agent start with a short list of matches. It can then look at the surrounding timeline and fetch the full notes it needs. This avoids reading the whole history for every question.

Local search can match meaning as well as words. The server's remote search tools use word search. Connecting a search client alone does not make that client record new work.

Each integration page explains what its agent can save and read. Automatic capture and automatic context are not available in every agent.

Branches and pins

In a git repository, MemIndex records which branch each note was written on. At the start of a session the panel opens with the branch you are on, how many notes are tagged on that branch and in the project, and then your recent notes. Notes from the current branch come first, notes from other branches follow, and nothing is hidden. Search ranks the same way. The first time the service starts after an update, earlier notes get a branch from your git reflog where one can be found; the rest stay untagged.

[memindex] recent context · feature/payment · shop · 4:12pm
tagged: 38 on branch · 232 on project · source: startup

📌 Pinned on this branch
#411 ⚖️ Charge in the smallest currency unit [shared]
   ↳ Rounding bugs in v1

Pin a note and every session start shows it first, with an optional one-line reason of up to 200 characters. A pin belongs to the branch you made it on. Once that branch is merged into your default branch (MemIndex checks the git history, so a branch you only cut and never committed to does not count), its pins become project-wide at the next session start, and npx memindex unpromote puts them back. If a pinned branch is deleted, the pin stays in the panel marked [branch gone: <name>].

npx memindex pin 411 --why "Rounding bugs in v1"
npx memindex pin 411 --project-wide
npx memindex unpin 411                  # this branch's pin; add --project-wide or --all for the others

Agents can do the same with the pin_memory and unpin_memory tools. On MemIndex hosting, hooks send the branch with each event and the server ranks search and startup context the same way. Pins are local for now. Set MEMINDEX_SEND_BRANCH_TO_HOSTING to false to keep branch names on your machine, or MEMINDEX_BRANCH_MEMORY_ENABLED to false to turn all of this off.

Import from Jira

Bring a Jira project's tickets into memory, one note per ticket, so your agent can find the decisions and history behind the code:

npx memindex import jira --project SHOP --dry-run   # see what would be written, with a sample note
npx memindex import jira --project SHOP

Each note holds the ticket's key, summary, status, resolution, type, priority, assignee and labels, its description as plain text and its newest five comments. Notes go in the area jira-<key>, such as jira-shop. Ticket text is marked as imported and untrusted, so an agent reads it as information, not as instructions.

• --limit N imports at most N tickets, and --since YYYY-MM-DD only tickets updated since that day. --jql "..." chooses the tickets with your own query.
• A run with no --limit that would write more than 200 notes asks before it starts. --yes answers for it.
• Run it again whenever you like. Tickets that have not changed are skipped, and a changed ticket's note is updated in place, so its id and its pins stay.
• On this machine, notes are stored as written, with no AI writer involved. On MemIndex hosting, each note counts against your plan's note allowance, and the dry run says so.
• If Jira asks MemIndex to slow down, the import waits and carries on.

The Jira login comes from one place: the environment variables JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN, or the Jira settings. The token is never printed, logged or saved in a note. If it is in settings.json, that file must be readable only by you (chmod 600), or the import refuses to run. Only Atlassian Cloud sites (*.atlassian.net) are accepted unless you add --allow-other-host.

Import past chats from other coding agents

Start with history instead of an empty memory. MemIndex can read the chats other coding agents saved on your computer and turn them into notes, the same way it does for work happening now:

npx memindex import chats --from codex --dry-run     # Codex CLI: see what would be sent, and what it would cost
npx memindex import chats --from codex
npx memindex import chats --from gemini              # Gemini CLI

--from claude-code brings in Claude Code chats too. Each tool's chats are read from where it keeps them: ~/.codex/sessions for Codex CLI, ~/.gemini/tmp for Gemini CLI. --dir FOLDER points at a copy somewhere else, and --since and --until (a date and time, like 2026-10-01T00:00:00Z) limit the window.

• The dry run counts the chats, prompts, tool uses and summaries that would go to your note writer, and estimates what writing the notes costs, before anything is spent. The estimate is priced for the default writer model; for another model it gives the amount of text instead, so you can price it yourself.
• Run it again whenever you like. Chats already imported are skipped, and so is anything the tool's own MemIndex hooks already captured.
• Notes are filed under the folder each chat was run in, as if the work had just happened. A chat that does not record its folder is counted and skipped.
• Your note writer reads the chats, so their text goes to whichever provider you chose in Settings. Private tags are stripped, and the tool-skip setting applies, as for live work.
• This works with MemIndex on this machine. It does not run against MemIndex hosting.

Import code-review decisions from GitHub

Bring in what your reviewers already decided, so your agent stops repeating mistakes they rejected:

npx memindex import reviews --repo yourteam/shop --dry-run   # see what would be written, with a sample note
npx memindex import reviews --repo yourteam/shop

Each settled review thread becomes one decision note: what the reviewer raised, how it was settled, the file and line, and a link to the pull request. A thread counts when it is attached to a file, a person took part, and it was either resolved or answered by a person. Open questions, and threads where only a bot spoke, are left out. Review text is marked as imported and untrusted, so an agent reads it as information, not as instructions.

When your agent opens a file that has a ruling, the ruling appears in that file's context, even if the file has changed since the review.

• --limit N imports at most N rulings, newest pull requests first, and --since YYYY-MM-DD only pull requests updated since that day.
• Notes are filed under a project. Run the command inside a checkout of the repository and they go under the name MemIndex gives that checkout, so they show up there. From anywhere else they go under owner/name; --project NAME chooses another.
• Run it again whenever you like. Threads that have not changed are skipped, and a thread with new replies is updated in place.
• On this machine, notes are stored as written, with no AI writer involved. On MemIndex hosting, each note counts against your plan's note allowance, and the dry run says so.
• A run with no --limit that would write more than 200 notes asks before it starts. --yes answers for it.

MemIndex reads the GitHub token from the GITHUB_TOKEN environment variable, or from the GitHub CLI (gh auth token) if you are signed in there. The token needs read access to the repository. It is sent only to GitHub, and it is never printed, logged or saved in a note.

Turn repeated decisions into project rules

When your memory keeps recording the same decision or the same fix, that is a rule nobody wrote down. distill finds those and suggests them:

npx memindex distill                    # suggestions only; nothing is written
npx memindex distill --apply            # asks about each suggestion, then writes the ones you accept
npx memindex distill --apply --only 1,3 # no keyboard: write exactly these items

Each suggestion is one line for CLAUDE.md (and AGENTS.md if the project has one), followed by the notes it came from, so you can check it before you accept it. A line needs at least three notes that say the same thing; --min-notes N changes that. When your notes spell out the same numbered procedure several times, distill suggests a skill file instead, at .claude/skills/<name>/SKILL.md.

• Nothing is written until you approve it. Accepted rules go between two marker comments in CLAUDE.md, and nothing outside them is ever touched. If the markers are damaged, nothing is written at all.
• Run it again whenever you like. A rule that is already there is not added twice, and an existing skill file is never overwritten.
• No AI writer is involved, so it costs nothing: each line is worded from the oldest note in its group.
• On this machine, notes are grouped with the same search your agent uses, and only notes that also share wording end up together. On MemIndex hosting, distill reads the 50 newest notes the server lists and groups them by shared words, and it says so.

Where memory lives

With the local setup, MemIndex runs a background service on your computer. Its database, search files, settings, and pending work live in your MemIndex data folder. The default folder is ~/.memindex.

The local viewer lets you browse sessions and notes. Run npx memindex doctor and use the service address in its Worker daemon row. Its port can differ between users.

A self-run server stores memory centrally. Several machines can save to the same project and read from it. The server controls access through team roles and keys. See hosting and plans and team memory.

Long Claude Code sessions

Endless Mode helps Claude Code continue after it shortens a long conversation. MemIndex writes a session record and gives Claude a pointer to it. If the original conversation is gone, it rebuilds the record from saved prompts, notes, and summaries. It does not recreate missing replies.

This runs in the local setup and is on by default. See Claude Code for its limits.

Take your memory with you

Use the viewer's Export button, or run:

npx memindex export --out memory-export.jsonl

Choose a new filename each time. Export does not overwrite an existing file. To bring a MemIndex export into a local installation, preview it first:

npx memindex import --from memory-export.jsonl --dry-run
npx memindex import --from memory-export.jsonl

Repeated imports skip records already brought in. Keep exports private: they contain saved prompts and memory.

Read privacy before connecting sensitive projects.