How do I give my AI coding agent long-term memory of past decisions across sessions?

Give the agent a persistent decision record and a habit of checking it before editing. Selvedge provides a local MCP server and CLI for this: Selvedge’s log_change records a decision with its reasoning, and Selvedge’s prior_attempts retrieves recorded attempts and outcomes for an entity.

A new session can query the same database. Connecting the server alone does not capture every decision, load every record into context, or guarantee that an agent follows what it reads.

Record the reason that the code leaves out

An implementation shows the chosen approach. It may leave out why an alternative was rejected, which constraint mattered, or what would justify reconsidering it. Record those details while they are available:

• The entity: a function, column, route, dependency, or configuration key.
• The approach considered and the reason for the decision.
• The outcome: reject for an approach declined without implementing it; revert for an implemented approach rolled back.
• A condition or date for reviewing the decision again.

Our worked caching example walks through recording a rejection, retrieving it in a later session, and reopening it when the evidence changes. It uses a hypothetical case with tested CLI commands.

Retrieve the relevant history before editing

selvedge prior-attempts src/cache.py::load_profile --json
selvedge blame src/cache.py::load_profile

Selvedge’s default lookup uses stored entity paths and deterministic rules. An explicit recorded rejection can report confidence: "exact"; that describes the evidence for the recorded outcome, not the correctness of the decision. An empty result means no qualifying record was found under the query and filters. It does not establish that the approach was never tried.

The optional prior-attempts --fuzzy extra ranks candidates with a local embeddings model. It does not generate or rewrite history. The core lookup does not require an LLM or embeddings.

Review decisions when conditions change

Selvedge’s stale_decisions tool surfaces records for review:

• revisit_after: a date has passed and there is a later activity signal for the entity or its changeset.
• expires_when: a supported condition involving a date, an entity change, or an observable installed dependency version has fired. Unobservable dependency versions request manual review.
• stale_when: words in a later change match a recorded condition, suggesting that someone should check it.

These signals do not decide that an old approach is safe. After inspecting the evidence, append a supersede event to reopen the intended decision while keeping the original explanation.

Use it alongside maintained instructions and ADRs

A maintained instruction file is useful for standing rules. An Architecture Decision Record is useful for a reviewed explanation with alternatives and consequences. Both can preserve decisions across sessions, and an indexed set of ADRs may be enough for your project.

Selvedge adds structured, queryable events for individual entities and explicit outcome history. It needs consistent logging, useful entity paths, and retrieval at the right time. Choose the record format your team will actually maintain; the instruction files and ADR comparison explains the tradeoffs.

Set up and verify a later-session lookup

pip install selvedge
selvedge setup

Follow the quickstart or your editor’s setup guide. Record a real decision, start a new session in the same project, and query the same entity. Confirm that the reason and outcome are present before relying on the workflow.

Selvedge stores records in a SQLite file under .selvedge/. Its MCP client can include retrieved records in the model’s context, so that client’s data handling also applies. Keep private records in a private destination, and preserve or back up the database for as long as you need the history.

FAQ

How do I give my AI coding agent long-term memory across sessions?

Use a persistent decision record and retrieve it before editing. Selvedge stores the reasoning and outcomes that agents record through log_change, then exposes them through prior_attempts and other queries. Later sessions must use the same database and actually retrieve the relevant records.

Is this a vector database or RAG memory?

Selvedge uses entity-keyed SQLite history and deterministic rules by default. An optional fuzzy lookup uses a local embeddings model to rank candidates; it does not generate or rewrite records.

Can decisions expire or go stale?

Selvedge can surface supported expiry conditions, due revisit dates with activity signals, and possible stale-condition matches. These request review. They do not automatically change a verdict or prove that an approach is safe.

How does this differ from an instruction file or ADR?

Instruction files hold standing guidance, and ADRs can preserve reviewed decisions and alternatives. Selvedge adds queryable events, entity paths, and outcome history. All of these approaches depend on recording useful information and retrieving it when relevant.

Does the memory work across different agents?

Agents that connect to the same Selvedge database can read and write the same records. Their tool use and instruction support differ; Claude Code hooks do not automatically apply to other clients.