Your coding agent has amnesia. Here's the memory architecture that fixes it.

Every coding-agent demo looks the same: a clean repo, a fresh context window, and a task that fits in one prompt.

Real work doesn't fit.

You make an architectural decision on Monday. On Tuesday the context compacts, the agent forgets why the decision was made, and it confidently proposes the opposite. You paste the schema again. You paste the ADR again. You explain, for the fifth time, that the auth service migrated from JWT to PASETO and why.

The model isn't the only problem. The interface is. A context window is a scratchpad, not a memory system.

I built Engraphis to fix this for my own workflow. This article is the architecture I landed on, the failure modes it addresses, and the parts I would measure before trusting any memory layer, including mine.

The failure mode: context is not memory

A coding agent has three kinds of state:

1. The current task, what you asked for, right now.
2. The working context, files, tool outputs, and conversation that fit in the window.
3. Durable project knowledge, decisions, constraints, invariants, and history that must survive the session.

Most agent setups treat all three as one thing: a growing transcript. That works until the transcript is compacted, truncated, or replaced by a new session. Then the third category disappears.

The usual workarounds have predictable costs:

• Paste everything into the prompt. Expensive, noisy, and still incomplete. A schema dump is not a decision record.
• Write a giant CLAUDE.md / AGENTS.md. Good for stable rules, bad for facts that change per repository, per branch, or per customer.
• Use a vector database of chat logs. Retrieval finds similar text, not the decision that is still valid, who made it, or which repository it applies to.
• Rely on the vendor's memory feature. Great when it works, but it is usually opaque, account-scoped, and not inspectable by the team that owns the code.

The result is the same: the agent has information, but not context with provenance.

Four properties of useful agent memory

Before choosing a database or a retrieval algorithm, define what the memory has to do.

1. Durable

A decision should survive a new session, a new branch, and a new machine. It should not depend on the current context window, a single chat thread, or a vendor's retention policy.

2. Scoped

"Use PostgreSQL" is not a universal fact. It might be true for one service, false for another, and irrelevant to a third. Memory needs workspace, repository, and session boundaries. Without scope, retrieval becomes a source of confident wrong answers.

3. Provenanced

Every recalled fact should be traceable to its source: the file, the commit, the conversation, or the decision record. If the agent can't show why it believes something, you can't debug it, and you shouldn't trust it with a destructive change.

4. Bounded

Retrieval should return the smallest useful context, not the most. A hard token budget forces the system to rank, compress, and omit. That is a feature. Dumping 50 KB of search results into a 200 K context window is how agents get slower, more expensive, and less accurate at the same time.

There is a fifth property that matters in practice: inspectable. You should be able to open a dashboard, search the memory, see its history, and correct it. A memory system you can't audit is a liability.

The architecture

Engraphis is deliberately boring at the storage layer and careful at the retrieval layer.

┌─────────────────────────────────────────────┐
│  Claude Code / Cursor / Codex / any MCP     │
│  client                                     │
└──────────────────────┬──────────────────────┘
                       │ MCP
┌──────────────────────▼──────────────────────┐
│  Memory service                             │
│  - remember / recall / session               │
│  - conflict review / history                │
│  - hard context budget                      │
└──────────────────────┬──────────────────────┘
                       │
┌──────────────────────▼──────────────────────┐
│  Local SQLite                               │
│  - scoped records                           │
│  - temporal validity                        │
│  - provenance                               │
│  - vector + lexical indexes                 │
└─────────────────────────────────────────────┘

Local SQLite, not a hosted vector store

The core stores memory in SQLite. That gives you a single file you can back up, inspect, and move. It works offline. There is no account requirement for the local core, and no data has to leave the machine.

The vector index is local too. The installed service uses a small local embedding model (about 80 MB on first download) with a deterministic offline fallback. The point is not to win a benchmark; the point is to keep the default path private and reliable.

Hybrid retrieval

A single retrieval mode is easy to demo and easy to break.

• Vector search finds semantically related memories even when the wording changes.
• Lexical search catches exact identifiers, error strings, and API names that embeddings blur.
• Graph traversal follows relationships between memories, files, and entities.
• Code-aware search understands that a symbol in a repository is different from the same word in a paragraph.

Engraphis combines these signals, then ranks and packs the result. The important design choice is that retrieval quality is measured separately from context size. A system that returns less context but loses the answer is not efficient; it is just wrong with fewer tokens.

Temporal history instead of silent overwrite

Facts change. A memory system that replaces the old value destroys the audit trail and makes it impossible to answer "what did we believe last month?"

Engraphis keeps history. A superseded decision can be closed rather than deleted, and the timeline can show what was valid at a given point. That matters for incident review, onboarding, and any agent that is about to change production code.

A hard context budget

Recall returns a bounded context package. The service ranks candidates, compresses them, and stops at a budget you set. The output includes the memory, its scope, and its provenance so the agent can cite it or abstain.

This is the difference between "search" and "memory." Search returns matches. Memory returns a defensible answer.

The MCP surface

The Smart profile exposes nine tools. The ones I use most:

Tool	What it does
engraphis_remember	Store a durable fact with scope and provenance
engraphis_recall_context	Retrieve compact project context
engraphis_session	Start or end a memory session
engraphis_get_memory	Read one governed record
engraphis_update_memory	Edit metadata without losing history
engraphis_conflict_review	Review pending, quarantined, or conflicting memories

There is also a Classic profile with 35 direct tools for clients that prefer explicit operations.

A minimal Claude Code setup looks like this:

python -m pip install "engraphis[mcp]"
engraphis-init
claude mcp add engraphis -- engraphis-mcp

For the local dashboard:

python -m pip install "engraphis[server]"
engraphis-dashboard
# http://127.0.0.1:8700

And the Python service, if you want to embed it:

from engraphis.service import MemoryService

memory = MemoryService.create("engraphis.db")
memory.remember(
    "Auth migrated from JWT to PASETO. Reason: issuer-bound tokens and key rotation.",
    workspace="acme",
    repo="api",
)
hit = memory.recall("Why did we change auth?", workspace="acme", repo="api")
print(hit["context"])

A worked example

Imagine the agent is about to add a new endpoint to the auth service.

Without memory, it sees the current code and infers the pattern. It might use JWT because JWT is common. It might miss that the team migrated away from JWT six months ago, or that one service is intentionally still on JWT during a migration window.

With scoped memory, recall returns something like:

Decision: Auth migrated from JWT to PASETO for the public API.
Scope: workspace=acme, repo=api
Status: current
Reason: issuer-bound tokens and key rotation requirements.
Supersedes: JWT decision (2025-11-03)
Evidence: docs/adr/014-paseto.md, commit 8f2c1a

Now the agent has a decision, a scope, a reason, a history, and evidence. It can follow the current pattern or ask a targeted question. It does not have to guess from a partial view of the repository.

That is the whole product thesis: the agent should be able to show its work before it changes yours.

What the benchmarks actually show

I am deliberately cautious here. The repository contains three deterministic offline fixtures. They are useful for regression testing the retrieval pipeline, not for claiming general task performance.

On those fixtures:

• Mean retrieved context dropped from 740.3 to 214.3 tokens per question, a 71.1% reduction across 18 questions.
• The serialized JSON-shape proxy dropped from 24,590 to 11,138 tokens across 26 payload samples and 260 recalls.
• Candidate and packed retrieval quality (Recall@5, Hit@5, and answer-token recall) were 1.000.
• Grounded checks: 5/5 answerable queries grounded, 6/6 abstention queries rejected, including a quarantined-evidence probe; 11/11 decisions correct.

These are small fixtures. They do not establish performance on your repository, your language, or your question distribution. MCP transport and provider billing were not measured. The full method, checksum, and reproduction steps are in the repository.

The right way to evaluate a memory layer is to build a small, labeled set of questions from your own codebase:

1. Pick 20 decisions or invariants that a new engineer would need.
2. Write the question a real agent would ask.
3. Record the expected answer and the source.
4. Measure recall, context size, and whether the agent can cite the source.
5. Include unanswerable questions. Abstention is a feature.

If a system can't abstain, it will hallucinate with confidence.

Try it, or have it set up for you

The local core is free and Apache-2.0:

python -m pip install "engraphis[mcp]"

Repository: github.com/Coding-Dev-Tools/engraphis

The optional Pro plan is $10/month or $100/year, with a 7-day trial and no card required. It adds hosted memory health views, scheduled upkeep, and optional sync. The local core stays free.

If you want the done-for-you version, I do a 24-hour Agent & MCP Rapid Setup for $250. That includes:

• clean setup of Claude Code, Cursor, or Codex;
• integration of up to three MCP servers;
• environment, credential, and security configuration;
• a one-page runbook;
• seven days of async text support.

No calls, no video, no screen-sharing. Text only, fixed scope.

Start here: engraphis.com or DM me with the two or three actions you want your agent to perform.

---

Disclosure: I built Engraphis. I used AI assistance to draft and edit this article; the architecture, code references, and benchmark numbers come from the Engraphis repository. The benchmark caveats are intentional, small fixtures are not a general performance claim.

---

Engraphis is live on Product Hunt now. The page is here: Engraphis on Product Hunt. I will answer questions there and in the comments.