How to Give Claude Persistent Memory With Graph-Vector MCP

Anthropic introduced Claude's memory feature in September 2025 for Team and Enterprise users. Dumping key-value notes into a system prompt or appending unindexed conversation history to a flat markdown file breaks as soon as a project spans weeks, multiple users, or conflicting technical decisions.

Most tutorials tell you to wire up an embedding model and dump text chunks into an isolated vector database. That treats memory as disconnected snippets instead of structured experience. Ask Claude about a choice made three sprints ago, and vector similarity alone pulls paragraphs with similar keywords. It misses the author who approved the choice, the pull request that reversed it, and the date it expired.

Persistent memory that works across sessions takes three ingredients: an explicit schema that captures entities and relations, an engine that handles graph traversal and vector search in a single query, and the Model Context Protocol (MCP) so Claude can query its own memory store safely.

Step 1: Decide what Claude should remember (entities, relationships, embeddings, timestamps)

Before touching a database configuration, define what counts as operational memory and what is disposable context. Storing every token Claude produces bloats retrieval windows and fills search results with discarded drafts and small talk. Real agent memory needs four primitives.

First, extract explicit entities. These are the persistent nouns Claude encounters: developers, microservices, repositories, third-party libraries, architectural decisions, and credential names. If a user tells Claude, "We switched our authentication service from Auth0 to self-hosted Keycloak," you don't want an amorphous paragraph. You want two entity nodes of type Service and an organization node.

Second, record named relationships between entities. Relationships give facts their context. Keycloak replaces Auth0. A developer authored an RFC. An API service depends on a Postgres database. Without relationships, a search for authentication can retrieve obsolete Auth0 configuration files next to new Keycloak endpoints.

Third, compute embeddings for semantic discovery. You can't predict the exact phrasing a user will use three weeks later. Attaching embeddings directly to entities and relationship descriptions lets the model search by concept, bridging "how do we log users in" and the Keycloak migration node.

Fourth, store timestamps on every insertion and edge update. Memory is chronological. An architectural decision made in January 2025 might be superseded by an issue resolved in March 2026. Without timestamps, Claude can't tell active company policy from deprecated legacy conventions.

Step 2: Model memory as a graph with vectors on nodes and edges

The naive memory setup puts text chunks into a vector table and calls it done. Vector tables can't answer structural questions, and traditional relational databases can't rank conceptual similarity. To give AI agents persistent memory, model the data as an attributed property graph where vectors live directly on nodes and edges.

In HelixDB, an open-source graph-vector database built in Rust, vectors are native properties rather than external pointers bolted onto a separate storage layer. A node representing a microservice holds standard property fields such as name, language, and deployed_commit, plus a top-level vector property for its architectural description. Vectors can also live on edges. A DEPENDS_ON edge connecting an ingestion service to a Kafka cluster can store an embedding of the failure-handling protocol.

This unified model removes the need to sync an external vector index with an application database. In multi-database setups, updating an entity in your relational store means triggering an update in your vector database. Network splits or delayed background jobs eventually make the graph and vector states drift. In HelixDB, transactions are atomic: graph topology and vector indexes commit or roll back together, so Claude never traverses an edge to an orphaned or mismatched embedding.

A graph also gives you clean multi-tenancy. Instead of spinning up separate infrastructure for every user or project, you can partition graphs logically by tenant tag, so private workspace notes stay isolated on shared infrastructure.

Step 3: Set write and read rules (when the agent saves memory vs recalls it)

An agent that writes to long-term memory on every turn quickly piles up duplicate, conflicting nodes. An agent that needs manual commands to save context gets forgotten by busy engineers. You need deterministic system-level rules for when Claude commits facts and when it runs memory lookups.

For reading, configure Claude to query its memory server at the start of any new session, or whenever a prompt references past events, architectural standards, user preferences, or project-specific terminology. Tell Claude to check its memory tools before answering with generic boilerplate. If a user asks, "What is our retry policy for webhooks?", Claude should search the graph before inventing an answer from public training data.

For writing, set a strict bar. Claude should write to memory only on three triggers: explicit user instructions (such as "Remember that we deprecate Node 18 by Q3"), verified decisions reached at the end of a multi-step debugging session, or declared user preferences. It should skip routine debugging attempts, wrong hypotheses, and conversational greetings.

Tell Claude to follow an upsert pattern rather than blindly inserting new entities. Before recording a fact about a service, the agent runs a read query to check whether that service already exists in the graph. If it does, Claude updates properties on the existing node or creates a timestamped edge to a new decision node. This keeps entities from multiplying and the graph navigable. Our guide on how to deduplicate entities in an agent memory knowledge graph covers concrete deduplication patterns.

Step 4: Recall with graph traversal plus pre-filtered vector search, not top-k alone

Standard vector retrieval relies on top-k nearest neighbor search. You pass an embedding of the user query, and the index returns the five or ten closest text chunks across the entire database. For agent memory this fails for one structural reason: vector similarity ignores connectivity.

Suppose you ask Claude: "Why did Sarah reject the Kafka proposal for our billing engine?" A standard top-k search scans every chunk mentioning Kafka, Sarah, or billing. It often pulls Sarah's biographical details, other Kafka implementations across the company, and generic billing documentation. The one note containing Sarah's exact objection might rank eleventh and get cut by the top-k limit.

Graph-vector retrieval fixes this with pre-filtering and multi-hop traversal. Instead of searching the whole index, Claude first resolves the initial entity: the Billing Engine node. From there, Claude traverses outward along active edges to find linked proposals and review nodes. HelixDB runs vector search directly over this graph-filtered candidate set rather than across the global index.

Pre-filtering scopes similarity calculations to related entities. The database evaluates semantic similarity only among the nodes connected to the billing architecture. HelixDB caps unrestricted global vector searches at 800 effective results to protect query budgets, and it applies this ceiling after candidate intersection during traversal-scoped lookups. If a candidate stream exceeds 1,000,000 unique entities, the query rejects cleanly rather than degrading into an unpredictable latency tail. With structural graph boundaries and vector ranking combined, Claude retrieves the exact rejection rationale without surfacing unrelated company chatter.

Step 5: Add time-range queries for recency (temporal modelling is manual)

Engineering knowledge goes stale fast. When Claude looks up coding guidelines, a standard vector search might return a heavily indexed documentation snippet from 2024 that contradicts a decision made yesterday. Claude needs a reliable way to rank recency above stale semantic matches.

Temporal modelling is not an automatic feature in HelixDB. You model temporal logic manually in your application schema. Store explicit timestamps on entities and event edges, using top-level properties such as valid_from, recorded_at, or superseded_at. HelixDB provides efficient time-range indexing, so queries can filter candidate nodes across historical windows without scanning every record.

When Claude writes a read query, it should combine property filters on these timestamp fields with its graph traversals. For instance, you can tell Claude to restrict policy queries to nodes where recorded_at falls within the last six months, or to filter out edges marked with an inactive status flag. Our guide on how to query agent memory by time range shows how these time bounds translate into fast range lookups.

Manual temporal modelling plus time-range indexes keeps Claude from hallucinating history. The agent ignores stale technical choices and still keeps the audit trail of past iterations.

Step 6: Run HelixDB locally and point Claude at the remote MCP server

Setting up the memory infrastructure takes minutes. The open-source HelixDB core is Apache-2.0 licensed and written in Rust, and it runs locally without heavy runtime dependencies. Install the Helix CLI to manage a local database instance on your workstation or staging server.

Initialize a local project workspace by opening your terminal and running:

helix init agent-memory cd agent-memory helix start dev

This boots a local development instance of HelixDB running SlateDB under the hood, accepting JSON queries at POST /v2/query. The engine can run fully in-memory, write persistent data to disk, or target S3-compatible object storage, depending on your configuration.

To connect Claude to your database, use the Model Context Protocol. HelixDB provides a remote MCP server endpoint at https://mcp.helix-db.com/mcp. This server exposes native agent discovery tools, so Claude can explore available database endpoints, construct queries, and safely mutate records without custom glue code.

To point Claude Desktop or Claude Code at the memory server, edit your configuration file (for Claude Desktop on macOS, that's ~/Library/Application Support/Claude/claude_desktop_config.json) to include the MCP server entry:

{ "mcpServers": { "helix-memory": { "url": "https://mcp.helix-db.com/mcp" } } }

Restart Claude Desktop. The hammer icon in the interface will show the HelixDB memory tools. Claude can now read and write graph-vector records across any conversation window.

Step 7: Understand the write flow: five-minute one-time confirmation, at-most-once writes

Giving an LLM autonomous write access to an operational database sounds terrifying, and without guardrails it is. Left unchecked, an agent stuck in an execution loop might write the same fact a dozen times, or overwrite critical entity properties when a prompt errors out.

The HelixDB MCP server blocks rogue writes with a two-tool confirmation protocol. A human developer session and an autonomous agent registration get entirely different tool catalogues. When Claude decides to record an architectural decision or insert an entity node, it can't mutate the database in a single direct call.

The write sequence takes two coordinated steps. First, Claude invokes a tool to generate a confirmation token for the proposed write. The token encodes the complete transaction: target nodes, edge definitions, property values, and embeddings. Second, Claude invokes the commit tool and passes that exact token back to the server to consume it.

This guarantees at-most-once writes. If Claude hits a network blip or an API timeout after minting the token, the write never commits. If the model retries with slightly altered text, the original token is invalid because the payload bytes no longer match. Once consumed, a token can't be reused, so an agent stuck in a loop can't insert duplicate edges. Claude gets autonomous persistence and the database keeps strict transactional boundaries.

What to do next: troubleshooting stale, duplicated or missing memories

Once your Claude memory MCP integration is running, watch how the agent uses its tools during real development sessions. Memory systems fail in predictable ways: records go stale, duplicate entities slip through on subtle spelling differences, or queries return empty sets because the filters are too strict.

When Claude misses relevant memories, inspect the query logs. Most often the agent is running global vector searches that miss context because the query has no entity anchor. Update your Claude system instructions to enforce a two-step recall pattern: first locate the root entity via full-text search or label matching, then traverse connected edges. HelixDB includes built-in BM25 full-text indexes alongside vector indexing, so finding exact names before a graph traversal is simple.

If you see duplicate entities, such as "AuthService" and "auth-service" existing as separate nodes, tighten your write prompt. Tell Claude to run a case-insensitive label check before calling the confirmation tool. If the entity exists, Claude should attach new observations as child nodes linked by an updated relationship instead of inserting a duplicate parent.

For enterprise agent deployments spanning multiple development squads or products, decide whether your workloads belong on local developer instances or centralized infrastructure. HelixDB Cloud provides managed, object-storage-backed deployments with horizontal reader scaling and high-availability gateways, so multiple agents can query the same institutional memory concurrently.

Conclusion

Persistent memory changes how you work with Claude. Instead of spending the first ten minutes of every chat re-explaining your architecture, team conventions, and past technical decisions, you pick up where you left off. But it only works if your storage engine can represent relationships, recency, and semantics together.

Don't spend weeks duct-taping a standalone vector database to a separate graph database. HelixDB combines graph traversal, native vector search, and BM25 full-text indexing in a single engine written in Rust. Run HelixDB locally, or connect your Claude client directly to https://mcp.helix-db.com/mcp and start building agents that actually remember.