Quickstart
From install to your agent's first remembered fact. You need Python 3.10+ and an MCP-capable agent. The setup command is tuned for Claude Code; other clients can run the server directly.
1. Install
$ pip install "kgl-memory[mcp]"This pulls in kgl-lang (the file format library) and the MCP SDK. For real semantic search instead of the default lexical search, add the optional extra (it downloads a small local model on first use):
$ pip install "kgl-memory[semantic]"2. Initialise your project
$ kgl-memory-init /path/to/your/projectThis is safe to re-run. It creates, never overwriting anything that exists:
memory/graph/with the schema and an orientation README for anyone (human or AI) who opens the folder;- a
kgl-memoryentry in the project's.mcp.jsonwith the absolute path to the graph; - a Claude Code Stop hook in
.claude/that nudges the agent to save notes after code changes.
.mcp.json has no path variables, so a relative path can silently point somewhere else. If you commit .mcp.json and share it, re-run kgl-memory-init on each machine.On Windows, if the command isn't on your PATH after pip install --user, use python -m kgl_memory.init /path/to/project.
3. Restart your agent
Restart Claude Code (or reconnect MCP servers) in that project, as for any MCP config change. Using a different MCP client? Run the server over stdio instead:
$ kgl-memory-mcp --root memory/graph --profile extended4. Tell the agent to use it
The server sends the agent usage instructions, but a short note in your project's CLAUDE.md (or equivalent) makes the habit stick:
## Persistent memory (kgl-memory MCP) An MCP server (`kgl-memory`) is connected to a KGL-based memory graph. Use it proactively; don't wait to be asked. - Before answering anything that might depend on prior context, call `get_context(query, session_id)`. - When the user states a fact or preference, or you make a decision worth recalling later, persist it immediately with `add_entity`, `record_preference`, `add_fact` and `link_entities`. - Only store things that were actually said or confirmed. Never invent facts.
5. Work normally, then look at what it learned
Use the agent as usual. When it records something you'll see files appear under memory/graph/. Open them. They're text.
$ kgl-memory-viewer --root memory/graph --port 8420The viewer opens a read-only dashboard at http://127.0.0.1:8420/ with a graph view, recent activity and search. See the viewer docs.
6. Commit it
$ git add memory && git commit -m "Agent memory: what we learned this week"That's the point. Review the diff like code, or see what one looks like. The server never creates git commits on its own.
Useful flags
| Flag | What it does |
|---|---|
--profile core|extended | Expose 6 core tools, or all 16. kgl-memory-init writes extended by default; the bare kgl-memory-mcp command defaults to core. |
--no-auto-extract | Turn off the background regex extractor that runs on add_message. Recommended when the agent writes memories itself. |
--no-semantic | Skip the local embedding model even if installed: fast, fully offline start-up. |
.kgl files, rebuild the index (see Maintenance).