eng-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@eng-server resume my last session and recall decisions about the auth flow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Engineering Continuity Graph
Local memory for AI coding sessions. A new chat forgets the decisions, constraints, and failures from the last one. Replaying the whole transcript is expensive and mostly noise. This project stores those facts as a small graph on your machine and returns only the connected neighborhood a new session needs.
The server stores, ranks, and enforces consent. It does not decide what a fact is. The coding agent does. Two rules hold for every run:
Nothing is stored without your consent.
Fact bodies enter a transcript only through an approved recall.
Design detail lives in the high-level design and the low-level design.
Architecture
The process is one local MCP server over stdio. SQLite is the only durable store. Proposals that you have not approved live in process memory and disappear on restart.
flowchart LR
subgraph client [Coding client]
Agent[Agent]
end
subgraph server [eng-server]
Tools[MCP tools]
Stage[In-memory staging]
Core[Ranking and neighborhoods]
Identity[Repository identity]
end
subgraph local [This machine]
Embed[Embedding provider]
DB[(SQLite graph)]
end
Agent <-->|stdio| Tools
Tools --> Stage
Tools --> Identity
Tools --> Core
Tools --> Embed
Core --> DB
Tools --> DB
Embed --> ToolsA session has two paths.
sequenceDiagram
participant Agent
participant Server
participant Staging
participant SQLite
Agent->>Server: ecg_get_session
Server->>SQLite: resume session, read stats
Server-->>Agent: memory block of titles or bodies
Agent->>Server: ecg_prepare_placements
Server->>SQLite: score candidates, read only
Server->>Staging: keep the proposal
Server-->>Agent: duplicate, supersede, related, or new
Agent->>Server: ecg_approve_consent
Server->>SQLite: record the grant
Agent->>Server: ecg_commit_step
Server->>SQLite: write facts, edges, provenance
Server-->>Agent: stored fact idsRecall never trusts a fact-id list from the caller. The server ranks the query, walks the edges, and returns whole facts grouped into clusters.
flowchart TD
Query[Query and entity names] --> Rank[Hybrid rank]
Rank --> Seeds[Top seed facts]
Seeds --> Walk[Breadth-first walk of edges]
Walk --> Split[Union-find into clusters]
Split --> Cap{Over token cap?}
Cap -->|no| Bodies[Fact bodies]
Cap -->|yes| Titles[Titles only]Related MCP server: waggle-mcp
What gets stored
Each fact is a title, a body, a type, a confidence, and the entities it mentions. Facts link to each other with weighted edges. A later fact can supersede an older one. The older fact stays in the graph so history remains readable.
Piece | Role |
Fact | The durable unit: title, body, type, status, confidence |
Entity | A deduplicated name such as a file, symbol, or concept |
Edge | A typed, weighted link between two facts |
Conflict | An unresolved contradiction or low-confidence supersede |
Exchange | The approved turns that explain why a fact was stored |
Suggested fact types are file, symbol, concept, decision, architecture, failure, requirement, discovery, and env_constraint. Other types are accepted.
Consent
Storage is default-deny.
Decision | Effect |
| One successful commit. A failed commit keeps the grant so a retry can use it. |
| Storage stays on for the rest of this session. |
| Recorded for audit. Does not authorize storage. |
| Storage stays off and further consent prompts stop. |
ecg_commit_step and ecg_approve_consent are the checkpoints. Their arguments are what you read in the client approval dialog.
Quick start
Python 3.11 or newer.
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytestRun the server on stdio:
eng-serverPoint an MCP client at that command with PYTHONPATH set to src, or install the package and call eng-server directly. scripts/setup.py can merge an entry into a local Claude desktop config. --print shows the entry and does not write. --force replaces an existing entry.
Optional neural embeddings, still offline:
pip install -e ".[embeddings]"The default provider is testing: deterministic 4-gram vectors, no model download. sentence-transformers and openai-transformers refuse to run unless the model is already cached.
Tools
Every tool name is prefixed with ecg_ so it does not collide with another MCP server in the same client.
Tool | Writes SQLite | What it does |
| Session row only | Start or resume a session and return a memory block |
| No | Score candidate facts and stage a proposal |
| No | Record merge, replace, or drop choices on that proposal |
| No | Stage the turns that explain the proposal |
| Grant row | Record your consent decision |
| Yes, under consent | Store facts, edges, and provenance for one exchange |
| No | Drop a staged proposal |
| No | Drop everything staged after you decline |
| No | Return the smallest fact neighborhood for a query |
| No | List open conflicts, titles and ids only |
| Yes | Keep the new fact, the old fact, or both |
| No | Counts for the repository |
Local commands
These talk to the SQLite file directly. Every path exits 0, including bad arguments, so a prompt hook cannot block you.
python -m eng_graph --repo . status
python -m eng_graph --repo . resolve_conflict
python -m eng_graph --repo . clear
python -m eng_graph --repo . clear --yesclear is a dry run until you pass --yes.
Configuration
Variable | Default | Meaning |
|
| SQLite file. |
|
|
|
|
|
|
|
| Above this, a recall degrades to titles and says why. |
|
| Write server diagnostics to stderr. |
Repository layout
src/eng_graph/
__main__.py MCP tools
state.py Sessions, consent, facts, edges, conflicts
core.py Placement, ranking, neighborhood, rendering
db.py SQLite connection and schema
repo.py Repository identity from files on disk
staging.py In-memory proposals
models.py Constants and request models
cli.py Local status, preview, and clear
embeddings/ Offline embedding providers
docs/
HLD.md High-level design
LLD.md Low-level designLicense and citation
Apache License 2.0. Copyright 2026 Mohd Aman. See LICENSE and NOTICE.
If you use this software, cite it with the metadata in CITATION.cff.
Available Tools
12 toolsecg_approve_consentA
Record the user's consent decision. This call is the consent checkpoint.
grant is one of approve_run, approve_session, reject,
or reject_session. The value must be the user's choice from the approval
dialog. Do not send approve_run or approve_session on your own.
approve_run authorizes exactly one successful commit.
approve_session authorizes storage for the rest of this session.
reject is an audit entry and never authorizes storage.
reject_session turns storage off and stops further consent prompts.
Any other string is recorded and does not authorize storage.
Inputs: grant (required), session_id (required).
ecg_cancel_stepB
Drop a staged proposal. No-op if it is already gone. Does not delete stored facts.
Inputs: session_id (required), exchange_id (required).
ecg_commit_placementsA
Stage the agent's chosen placement actions. Does not write durable memory.
exchange_id is the prep_id from ecg_prepare_placements.
Use this to record merge, replace, or drop decisions before the user
approves ecg_commit_step. Dropped placements must not be sent on later
as if they were approved.
Inputs: placements (required), session_id (required), exchange_id (required).
ecg_commit_stepA
Store approved facts for one exchange. This call is the storage checkpoint.
The arguments are shown to the user in the native approval dialog. Pass the
real title and body of every fact. Do not substitute "see above",
a hash, or an empty placements list to hide what will be saved.
exchange_id is the prep_id from prepare, or a new id when committing
placements directly. messages are provenance turns. Each placement uses
the same fields as a candidate, plus action and optional
supersede_existing_fact_id / target_fact_id.
Storage is refused unless the session has approve_session or an
unconsumed approve_run grant. One successful commit consumes one
approve_run grant. A failed commit does not consume it.
An explicit supersede at confidence >= 0.75 marks the old fact superseded
and links supersedes. Lower confidence, or an ambiguous target, keeps
both facts and opens a conflict instead of overwriting anything.
Inputs: messages (required), placements (required), session_id (required), exchange_id (required).
ecg_discard_proposalB
The user declined the staged proposal. Drop it. Do not store it later.
Inputs: session_id (required).
ecg_get_sessionA
Start or resume the engineering-memory session for a project path.
Returns session id, repository id, stats, a short repo map, consent state,
and separate database and embeddings status objects. If one of those
is degraded the other is still reported. This call does not store facts.
Pass the project root (or any file inside it), not a login secret.
Inputs: path (required).
ecg_list_conflictsA
List open supersession or contradiction conflicts. Titles and ids only, no bodies.
Inputs: session_id (required).
ecg_prepare_placementsA
Score candidate facts against the repo and stage a proposal. Does not store.
Each candidate needs title and may include body, fact_type,
entities (name, entity_type), confidence (0..1), and
action (new, update, create, merge, replace, drop, supersede).
Unknown fact and entity types are accepted.
The result is a prep_id (also returned as exchange_id) plus a
classification for each candidate: likely_duplicate, possible_supersede,
related, or new, with the matched fact titles and scores.
The proposal lives only in process memory. Abandoning it leaves no database row.
Inputs: candidates (required), session_id (required).
ecg_record_provenanceA
Stage conversation turns that explain a proposal. Does not write durable memory.
Each message is {"role": "user"|"assistant", "content": "..."}.
Full text is stored only if a later ecg_commit_step succeeds under consent.
Inputs: messages (required), session_id (required), exchange_id (required).
ecg_resolve_conflictA
Resolve open conflicts. This call is the user's choice, not a silent overwrite.
resolution is new (keep the new fact, supersede the old), old or
existing (keep the old fact, supersede the new), or both (keep both
active). History is kept: the loser is marked superseded and linked, never
deleted. conflicts is a list of conflict ids from ecg_list_conflicts.
Inputs: conflicts (required), resolution (required), session_id (required).
ecg_search_contextA
Return the smallest fact neighborhood for query. This is the only body export.
The server ranks facts itself from query and entity_names. It does
not accept a fact-id list, so a caller cannot widen an approval by naming
extra facts. Results are connected clusters labeled by their shared entity
(or the top fact title). When the rendered block would exceed
ECG_AUTO_INJECT_MAX_TOKENS, or ECG_AUTO_INJECT=preview, the block
contains titles only and says why.
Inputs: query (required), session_id (required), limit, entity_names. Returns: result
ecg_statsB
Read-only counts for the session's repository.
Reports exchanges, active facts, superseded facts, total facts, edges, entities, and open conflicts. Fact bodies are not included.
Inputs: session_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Tools divide into distinct workflow stages (session start, prepare, commit placements, commit step, search, conflicts), and descriptions explicitly clarify which call stores versus stages data. Some overlap exists between ecg_commit_placements and ecg_commit_step, and between ecg_cancel_step/ecg_discard_proposal, which could confuse ordering, but the descriptions distinguish them.
All tools use a consistent ecg_ prefix followed by verb_noun snake_case (ecg_prepare_placements, ecg_commit_step, etc.). A few names like ecg_stats and ecg_search_context are noun/short forms, but the convention is otherwise predictable.
12 tools is well within a healthy range and each maps to a distinct step in the memory workflow. The set is neither thin nor bloated for the stated purpose.
The surface covers the full lifecycle: session init, preparation, staging, provenance, consent, commit, cancellation, search, conflict listing/resolution, and stats. No obvious CRUD or lifecycle gaps remain.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent knowledge graph for AI-augmented teams. Store decisions, findings, and standing rules across agent sessions with semantic search and typed connections. Includes cross-session memory, audit trail, workspace isolation, and secret detection. Built for teams running agents that need to remember. Free until launch with team tier as default, anon trial available.
Private memory for AI agents: save and recall facts across Claude Code, Codex, Cursor and ChatGPT.
Persistent knowledge graph for AI agents. Remember, recall, and forget facts.
Related MCP Servers
- AlicenseAqualityCmaintenancePersistent, local-first graph memory for AI coding agents. Provides durable cross-session memory via a local SQLite knowledge graph with typed relationships.61MIT
- AlicenseNot gradedqualityDmaintenanceProvides coding agents with persistent graph-backed memory, storing decisions, reasons, and contradictions across sessions so conversations pick up where they left off.Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI agents to maintain a persistent knowledge graph of a project, providing dependency context, impact analysis, side-effect discovery, and session recording for more informed coding decisions.5MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to read and write persistent memory directly during sessions, storing decisions, preferences, error patterns, research, and cross-project guidelines in local SQLite databases. Supports semantic search so relevant project and global context can be recalled by meaning, fully offline and without API keys.-