โ† Back to Blog๐Ÿ‡ฎ๐Ÿ‡น Leggi in Italiano

How to Give Claude Code Persistent Memory: A Practical Guide

A step-by-step operational guide to wiring a knowledge graph into Claude Code, so project decisions survive across sessions instead of being re-explained every time.

If you've read why Claude Code forgets context between sessions, here's the practical side: how to wire persistent memory into your project, step by step. This isn't a conceptual guide to what a knowledge graph is (that's here): it's the sequence of actions to have one working today.

I'm using the VibeCoded Orchestrator (VCO) as the reference, the tool I know best because it's the one I use every day: it's free, open source (AGPL-3.0), and runs entirely on your machine, no project data leaves your computer. The steps stay valid in principle even if you use a different persistent-memory system: the tool changes, not the logic.

$ npx vco-installer initWiring knowledge graph... doneStarting MCP servers... done
01
Install the orchestrator through the launcher

The most direct path is through the VCT Launcher, the free desktop hub (Tauri 2) that manages installing and wiring up agents, skills, hooks, and MCP servers. The onboarding wizard detects your system, downloads the local AI models needed to generate embeddings, and starts the knowledge graph services.

terminal

git clone https://github.com/hotak92/vibecoded-orchestrator cd vibecoded-orchestrator

If you prefer the manual route without the launcher, the GitHub repository includes the command-line install script. The launcher remains the fastest path if you don't want to manage containers and local models by hand.

02
Register the project

Once the orchestrator is installed, register the folder of the project you want to work on. This step creates the .claude/ structure inside the project: this is where agents, skills, automation hooks, and the knowledge/ folder live, where the knowledge graph keeps its nodes as Markdown, not in a closed binary database.

The practical advantage of readable .md files: you can open them, edit them by hand, version them with git like any other project file. There's no proprietary storage to depend on.

03
Open the project with Claude Code

With the Claude Code extension in VS Code (the primary target) or the standalone CLI, open the folder of the project you just registered. Agents, skills, and hooks are already active. From this point on, every time the AI writes a relevant architectural decision to a knowledge graph node, a PostToolUse hook intercepts the save, generates the embedding, and indexes it automatically within seconds. You don't call any "memory.add()" function by hand: it happens on its own when you write or edit a file inside knowledge/.

04
Write your first decision as a node, not as a code comment

This is where the practical difference lies compared to leaving everything scattered across commits or code comments. When you make a decision you want to survive future sessions (why you chose JWT over sessions, why an endpoint is structured a certain way, which library you ruled out and why), write it as a knowledge node:

knowledge/decisions/auth-strategy.md

Authentication strategy

Chose short-lived JWTs with refresh tokens instead of server-side sessions.

Why: the service needs to scale horizontally without shared state between instances. Sessions would require a centralized store (Redis), complexity that isn't needed at the current volume.

Related to: [[uses::FastAPI]], [[extends::Base Auth Middleware]]

The double square brackets ([[uses::FastAPI]]) are typed wikilinks: they connect this node to other concepts in the graph, so a future search can trace not just the text but the relationships between decisions.

05
Query the graph instead of re-explaining

From here on, in a future session (even weeks later, even in a different project if you use the cross-project shared collection), instead of re-explaining the context you can simply ask. The agent queries the knowledge graph with a targeted question and gets back only the relevant nodes, not the entire project history:

prompt in Claude Code

What did we decide about the authentication strategy and why?

The search (hybrid_search in VCO's case) combines semantic similarity with traversal of typed links: it doesn't just find text that resembles the question, it can follow the found node to connected concepts, for example reaching the middleware that depends on that choice.

06
Let the graph maintain itself

With daily use, the graph grows alongside the project. A dedicated knowledge-curation agent (in VCO's case, called knowledge-curator) periodically reviews new nodes, proposes missing links between similar concepts, and flags content that's become outdated. It's not a step you run manually every week: it's meant to run in the background, so the cost of maintaining memory stays low even as the number of nodes grows.

What to expect in practice

The change isn't "the AI magically remembers everything": it's that the work of maintaining context shifts from "re-explain everything out loud every time" to "write it once in a structured place, queryable later." The first week requires the discipline of writing nodes when you make a decision, instead of leaving it only in your head or in a commit message. After that, the payoff shows up most on projects that live for months, or that you return to after a break: the difference between reopening a project and immediately understanding why it's built a certain way, versus having to reconstruct it all by reading old code.

The base orchestrator, including the full knowledge graph, code graph, and automation hooks, is free under the AGPL-3.0 license: VibeCoded Orchestrator.