The problem
My projects span repositories, machines, deployments, and design decisions. A useful agent needs to remember how those pieces relate: which application inherits a template, where a service runs, and why a previous implementation changed. Local notes and session-specific memory made that context difficult to carry into the next conversation.
I built graphmem around a shared knowledge graph. A memory has a stable name, a short explanation, provenance, and explicit connections to other memories. Claude and Codex sessions can consult the same store through MCP instead of depending on the history of one chat. The goal was continuity across sessions, with a graph I could inspect and maintain myself.
The implemented architecture
The Oracle-backed implementation has three interfaces: a stdio MCP server, a CLI, and a FastAPI graph explorer. Each calls the same graphmem.core module. That keeps retrieval and write behavior consistent across an agent conversation, a terminal command, and a browser view.
Oracle Autonomous Database holds nodes, edges, and a vocabulary registry. Nodes separate a compact title and summary from an optional longer body. They also carry tags, aliases, source, confidence, verification dates, and lifecycle status. Edges have a relation type, direction, weight, and explanatory note. Database constraints protect unique node names, valid statuses, and duplicate relationships.
Embeddings are generated inside Oracle using an ONNX all-MiniLM-L12-v2 model. The embedding input combines title, summary, and tags; the schema stores a 384-dimensional vector. Semantic recall orders memories by cosine distance and returns compact matches with their edge references. A client can then request a full node or traverse its neighborhood. The database connection uses wallet-based credentials; a new machine needs access to that same database, not a copy of its contents.
Engineering decisions
One core, several thin interfaces. The MCP tools translate arguments into core calls and serialize their results. The web explorer exposes graph, node, recall, and traversal endpoints. Keeping these wrappers small makes fixes to graph behavior reusable across entry points.
Summaries drive retrieval. Long bodies remain available through get, while list-like responses stay compact. This makes the distinction between finding relevant context and loading detailed evidence explicit. It also places responsibility on the writer to produce a useful summary.
Writes check for duplicates first. remember embeds a candidate, examines nearby memories, and returns probable duplicates below the configured cosine-distance threshold of 0.30. A caller can update or link an existing memory, or explicitly override the check. Successful saves suggest related nodes; creating those relationships remains a separate action. The threshold is a heuristic, not a published accuracy result.
Vocabulary grows as data. Domains, kinds, and relation names live in a registry. Writes accept registered values, normalize capitalization, and return guidance for unknown entries. Adding a new category does not require changing the node table. This preserves flexibility while discouraging accidental naming drift.
Semantic search and traversal serve different questions. Recall finds a relevant starting point. The shipped walk expands neighboring nodes in bounded hops, across both edge directions, with optional relation and minimum-weight filters. It does not learn edge weights from usage. Exact keyword search uses case-insensitive substring matching in the inspected implementation.
A concrete workflow
A design change can become a decision node linked to a template and the applications using it. A later session recalls the design topic, inspects the decision, and follows those links to affected projects. The agent still needs to verify the current repository state before applying a change.
For a graph containing an illustrative example-project node, the CLI supports:
graphmem recall "which design decisions affect this project"
graphmem get example-project
graphmem walk example-project -d 2
graphmem search --domain design
The explorer provides a complementary visual way to inspect the same relationships.
Evidence and evolution
The initial Oracle design dates to July 2026. The public v1.0.0 release added clearer database-unavailable errors, duplicate-name handling, stricter configuration parsing, and a unit suite using pure helpers and mocked database cursors. It also tightened secret-body and attribute redaction on web node details and default exports, and rejects partially configured web authentication.
The inspectable evidence is the schema, shared core, interface code, release notes, and tests. I have not published a controlled retrieval-quality, latency, or throughput benchmark for this project.
Limits and operational tradeoffs
The embedding model is English-centric; the tool guidance recommends English recall queries and keyword search for exact non-English terms. Oracle also creates a provisioning dependency. SQLite and PostgreSQL adapters appear in the design roadmap, but are not implemented in the inspected release.
Connection pooling and transactional rollback for interrupted imports remain future work. A keepalive utility handles database lifecycle operations, and JSON export/import provides a portability path. Credentials belong outside the knowledge graph: even when a body is redacted, its title and relationships remain visible. The deployment needs authentication and a tested backup process appropriate to the memories it holds.