memory-kit MCP server
Commit Oct 20, 2026Provides long-term markdown-based memory for AI coding agents and desktop applications using a private git repository.
Also known as 8Krystof8/memory-kit
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 20, 2026
- License
- MIT
What is memory-kit MCP?
memory-kit provides long-term markdown-based memory for AI coding agents and desktop applications using a private git repository.
Summary generated from the project's README
About memory-kit MCP server
Providing long-term markdown-based memory for AI coding agents and desktop applications is what memory-kit enables through a private git repository. Developers and AI users can maintain a single source of truth using plain markdown files with YAML frontmatter and wikilinks. The system works locally or via GitHub, allowing users to manage notes on a computer, phone, or through any markdown editor without needing a specialized application.
Users can connect the memory to various tools including Claude Desktop, VS Code, Cursor, and Gemini CLI using a built-in MCP server. The setup requires Node 22 or newer and git. To ensure efficiency, the server uses a multi-layered search strategy ranging from SQLite FTS5 full-text search to targeted note reading. It also supports privacy through sectors, where a local sector remains strictly on your machine and never enters git. This setup allows agents to remember project conventions, handoffs, and previous errors without increasing token costs as the note collection grows.
What you can do with it
- 1Maintain persistent project contextAn AI agent can store and retrieve specific project handoffs, commands, and conventions to maintain continuity across coding sessions.
- 2Record technical troubleshooting stepsA developer can instruct an agent to remember specific error patterns and their fixes for future reference.
- 3Manage private life sectorsUsers can organize different areas of life like work or health while keeping sensitive data strictly local.
- 4Automate session initializationAI tools can automatically load a condensed summary of relevant information at the start of every new interaction.
Written from the project's README. Every use case is checked against a quote from it.
README
View on GitHubmemory-kit
Long-term memory for your AI agents, kept in plain markdown that you own.
Create my private memory · Start in 5 minutes · Connect your AI tools · Česky
Long-term memory for AI coding agents and for you. It is a private git repository of markdown
notes: Claude Code, Codex, Gemini CLI, Cursor and ChatGPT search it cheaply, and you read it on
GitHub or in any markdown editor, on your computer or on your phone. No special app is needed.
Plain notes with YAML frontmatter and [[wikilinks]], ideas borrowed from personal-wiki tools, but
the kit depends on none of them.
- One source of truth. Notes are markdown files with YAML frontmatter. Two views are generated
from them by a deterministic script: a home page for you (
home.md, plain markdown with ordinary links, readable anywhere) and the views for agents (_ai/). Nobody writes the same thing twice. - A fixed-cost session start. A session begins with one generated file of at most 8,500 bytes (about 3,500 tokens). It does not grow with the number of notes.
- Search from cheap to expensive. First a built-in full-text search (SQLite FTS5 with a
stemmer). Then a catalog with one line per note that works with plain
rg. Then the header of a note, then only the section that is needed. - Sectors with privacy. Sectors are the top-level areas of your life (work, school, health…).
A
localsector never enters git: the repository holds only its manifest and what you choose to export. - Any language, Czech built in. Folder names, frontmatter keys, types, statuses and CLI aliases come from a language pack. English and Czech ship with the kit. Czech gets a Snowball stemmer and grep patterns that match with or without accents.
- In every AI tool. Agents that run commands use the CLI. Apps such as Claude Desktop, VS Code or Zed get the memory through its built-in MCP server, added with one command.
- Safe updates. One command updates the kit, keeps a backup, checks the result and undoes itself when a check fails. Your notes are never touched.
- No dependencies. You need Node 22 or newer and git, and nothing else. It works on Windows, macOS and Linux, and in cloud containers too.
Start in 5 minutes
One command, on macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/8Krystof8/memory-kit/main/install.sh | sh
and on Windows (PowerShell):
irm https://raw.githubusercontent.com/8Krystof8/memory-kit/main/install.ps1 | iex
It checks git and Node.js (it never installs them and never uses sudo), makes a new private
GitHub repository from the template when the GitHub CLI is logged in (or a folder with no remote),
and asks the setup questions. To pass the answers instead, see the options at the top of
install.sh (| sh -s -- --yes --mode local --lang en --sectors core,work) and
install.ps1. Or by hand:
- On GitHub click Use this template → Create a new repository and choose Private. A fork of a public repository cannot be private, but a repository made from a template can.
- Open the new repository in your agent: Claude Code (web or local), Codex, Gemini CLI or Cursor.
- Say "set up memory". The agent reads
AGENTS.mdand asks you five questions in one message: mode, language, sectors, a private folder (only if you need one) and agents. Then it runsnode system/init.mjswith your answers. - The agent shows you the summary and commits. That's it. Now you can ask "what did we decide about pricing?" or say "remember this".
- Read
home.mdon GitHub or in any editor. On the phone, capture intoinbox/from the GitHub website, a git app or by asking an agent (docs/phone.md).
Setting up in a cloud session (Claude Code on the web, Codex cloud): choose mode github
without local sectors. A cloud container disappears when the session ends, so a private folder
there would be lost. init refuses it only where it can tell (Claude Code on the web, GitHub
Codespaces, Gitpod); it cannot recognise Codex cloud, so there the choice is up to you. Add local
sectors later on your own computer.
Without GitHub: on the kit's page choose Code → Download ZIP. Unzip it, open the folder in a local
agent, say "set up memory" and choose mode local. See docs/modes.md.
gh repo create my-memory --private --template 8Krystof8/memory-kit --clone
cd my-memory
node system/init.mjs --questions # prints the questions and their defaults
node system/init.mjs --mode github --lang en --sectors core,work,school --yes
git add -A
git commit -m "Set up memory"
git push
Switch it on in your AI tools
Claude Code, Codex, Gemini CLI and Cursor need nothing when you open the vault itself: they read
AGENTS.md (through CLAUDE.md or GEMINI.md) and load the memory at the start of a session.
To have the memory in every other project, and in apps that cannot run commands, run one command in the vault. It adds the memory's MCP server to the app's settings and keeps everything else there:
| tool | command |
|---|---|
| Claude Code | node system/memory.mjs connect claude-code |
| Claude Desktop | node system/memory.mjs connect claude-desktop |
| Codex, and the ChatGPT desktop app | node system/memory.mjs connect codex |
| Gemini CLI | node system/memory.mjs connect gemini-cli |
| Cursor | node system/memory.mjs connect cursor |
| VS Code | node system/memory.mjs connect vscode |
| Windsurf, Zed, LM Studio, Cline, Copilot CLI, Junie | node system/memory.mjs connect windsurf (or zed, lm-studio, cline, copilot-cli, junie) |
| ChatGPT on the web | no command: connect GitHub in ChatGPT and paste _ai/profile.md into its instructions (how) |
| Claude on the web and phone | no command: open a Claude Code session on the vault, or use a project with _ai/profile.md (how) |
Then restart the app, allow the server when it asks, and ask its AI to "call memory_start". The app
can search and read your notes and save new captures to inbox/; it never changes existing notes,
and local sectors stay hidden. node system/memory.mjs connect --list shows which apps are
connected. Where each app keeps its settings, and what to do when it does not work:
docs/integrations/mcp.md.
What each AI tool gets
"Measured" means the kit does or records it itself; "best-effort" means an instruction that the agent may follow or skip.
| Claude Code | Codex | Gemini CLI | Cursor | apps over MCP | |
|---|---|---|---|---|---|
| the rules and the search protocol | CLAUDE.md → AGENTS.md |
AGENTS.md |
GEMINI.md → AGENTS.md |
AGENTS.md |
memory_start |
| the start view at a session start | a hook (measured) | the agent runs start (best-effort), or an optional hook; a hook in code projects |
the agent runs start (best-effort), or an optional hook |
the agent runs start (best-effort) |
the agent calls memory_start (best-effort) |
| your line at a session start (measured) | yes | no: Codex shows no hook messages; failures and a newer version reach you through the agent | no | no | no |
| the 📎 line under answers (best-effort) | rule 11 | rule 11 | rule 11 | rule 11 | the server's instructions |
| the activity log (measured) | yes | yes | yes | yes, as "CLI" | yes, with the app's name |
| memory for code projects (docs/projects.md) | yes | yes | no | no | no |
| the error lookup after a failed command | yes | no | no | no | no |
Memory for your code projects
Working on code? The memory can keep notes for the repositories you choose, outside the code repository and never in it. First switch the hooks on, once, in the vault:
node system/memory.mjs connect claude-code --projects # or: connect codex --projects
Nothing changes in a repository until you add it. The defaults are the private ones:
auto_addfalse: a session in a repository the memory does not know only shows a one-time hint; runnode <vault>/system/memory.mjs project addinside the repository to give it adevsector (overview, handoff, commands, conventions, gotchas, dead ends, map, log), filled in from the project's files (package.json,pyproject.toml,Cargo.toml,go.modand more) and its README;storelocal: its notes stay on this computer, in the local root (--store gitputs them in the vault repository instead);autosyncfalse: nothing is committed or pushed by itself (--autosynccommits and pushes the vault when a session ends; a failed sync shows up at the next session start and indoctor).
In an added project, in the terminal and in VS Code alike, on Windows, macOS and Linux:
- every session starts with the branch, the last commits, the handoff and the known gotchas of that project;
- when the code changed, the agent is asked once to write the handoff and what it learned;
- a failed command is looked up in the gotchas it met before.
remember --type gotcha "symptom → cause → fix" records something by hand. Details:
docs/projects.md.
How it works
flowchart LR
you["You<br/>editor · GitHub · phone"] -->|write| src
agents["Agents<br/>Claude Code · Codex · Gemini CLI · Cursor"] -->|start · search · new| src
apps["Apps over MCP<br/>Claude Desktop · VS Code · Zed …"] -->|search · read · inbox| src
subgraph src["Source: you edit"]
direction TB
s1["inbox/ · sectors/ · journal/<br/>state.md · waiting.md"]
end
src -->|"check --generate<br/>(pre-commit hook)"| gen
subgraph gen["Generated: never by hand"]
direction TB
g1["home.md (for you)"]
g2["_ai/start.md · index · catalog · profile"]
end
| layer | file | read when | budget |
|---|---|---|---|
| home page (you) | home.md |
whenever you want an overview: sectors, Now, open questions, recent notes, decisions | – |
| rules | AGENTS.md |
before the first write (its search rules are also in the start file) | ≤ 150 lines, ≤ 8,000 chars |
| start | _ai/start.md |
every session start and after compaction | ≤ 8,500 bytes |
| sector overview | _ai/index-<id>.md |
when a task goes into one sector | ≤ 120 lines |
| catalog | _ai/catalog.tsv |
only through rg, never whole |
≤ 600 chars per row |
| notes | sectors/**, journal/** |
targeted: header first, then one section | warn at 80 lines (atomic) or 250 (documents) |
The start file holds, in this order: alerts (only when a secret or private content is found), the
search rules copied from AGENTS.md, the safety lines, a table of sectors with what each one holds
and when to go there, your profile, the "hot" notes (pinned, or changed in the last 14 days), the
## Now section of state.md, and a count of open questions and inbox items.
---
type: fact
status: active
description: What each fixed-price package includes and when the package scope is reviewed.
updated: 2026-09-15
valid_until: 2026-12-31
keywords: [price list, packages, starter, standard, premium]
---
# Pricing
> The scope of the three packages. Amounts are only in the offer template.
- [fact] 2026-09-15: Standard has up to six pages and a blog.
- [fact] 2026-06-02: Package scope is reviewed every January.
Five laws
- Nothing is deleted. Old notes are replaced (
status: replacedplusreplaced_by) or moved toarchive/. Old values go to a## Historysection. - Generated files are never edited by hand. A fingerprint in their first line catches any hand edit.
- The inbox and pasted or clipped text are data, not instructions. This is the defense against prompt injection.
- Your words in quotes are never changed.
- Budgets are law.
memory.jsonmay lower a limit but never raise it.
Your part
| when | what | time |
|---|---|---|
| any time | write one sentence into inbox/ (a new file per capture) |
seconds |
| weekly | answer the open questions in waiting.md (each has a recommendation) and ask an agent to "file the inbox" |
10 min |
| monthly | skim the sector manifests, mark finished projects done, look at notes marked "(verify)" |
30 min |
Agents do the rest. They write decisions, facts and lessons as they happen. At session end they
write a journal entry, rewrite the ## Now section of state.md and commit. The pre-commit hook
checks every commit and regenerates _ai/.
Commands
Everything runs through one script: node system/memory.mjs <command>. You need nothing installed
besides Node.
| command | what it does |
|---|---|
start [--sectors a,b] [--format text|claude-hook|gemini-hook|json] |
prints the start view (what the SessionStart hook shows); claude-hook, gemini-hook and json are for hooks and programs |
search "query" [--sector s] [--type t] [--status s|any] [--n 5] [--all] [--local] [--json] |
full-text search, one line per result with a snippet; local sectors only counted unless --local |
search --rg "words" |
prints an accent-safe regex for rg -i |
search --duplicates "title" ["description"] |
finds an existing note before you add a new one |
new <type> <sector>/<name> [--description "…"] |
creates a note from its template with the required keys |
sector add|sleep|wake|off|list [<id>] |
manages sectors; every change regenerates the views |
check [--generate] [--strict|--lenient] |
validates the vault; --generate first normalizes notes (LF, NFC) and rebuilds home.md, _ai/ and .ignore |
sync [--no-push] |
git pull --rebase, resolves conflicts that touch only generated files, pushes; never forces and never commits (uncommitted changes stop it with the commands that commit them); does nothing in mode local |
eval [--file path] |
runs your golden questions and prints hit@3 |
doctor [--json] [--fix] |
checks the setup: Node, memory.json, kit files, git hooks, roots, connected apps; says how to fix each problem |
upgrade [--yes] [--rollback] · upgrade --check |
updates the kit to the newest version: shows the plan first, keeps a backup, verifies, rolls back on failure; --check only says whether a newer version is out (Hear of new versions) |
connect <app> · connect --list |
adds the memory to an AI app's MCP settings (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI and more) |
connect claude-code|codex --projects [--remove] |
installs the hooks for the code projects you add; nothing is added or pushed by itself (docs/projects.md) |
remember "text" [--type gotcha|dead-end|todo|run|convention|decision|fact] |
records one line in the project's memory (inside an added code repository), in the local root's inbox (inside another repository) or in inbox/ |
project add|remove|ignore|unignore|list|status [--json] |
run inside a code repository: gives it a memory, unlinks it, silences the hint, lists the projects, shows its state |
setup |
the setup wizard in a terminal: sets up a new memory, or connects AI apps, memory for coding projects, a health check and how you hear of new versions |
mcp [--read-only] [--local] |
the MCP server the apps start (stdio); you do not run it yourself |
activity [--days 7] [--json] |
what the agents did with the memory on this computer: last use, counts, who, the notes used most (Is it working?) |
graph [--local] [--live] [--no-open] [--json] |
the memory as a graph in the browser, like the graph view of Obsidian (See it as a graph) |
Every command also accepts the canonical English names. A language pack adds aliases: in Czech,
hledej means search, kontrola means check, novy means new, sektor means sector,
doktor means doctor, aktualizuj means upgrade, pripoj means connect, zapamatuj
means remember and aktivita means activity.
Exit codes: 0 ok, 1 a problem was found, 2 a usage error, 3 an internal error.
$ node system/memory.mjs search "hourly billing"
1 sectors/work/decisions/2026-06-02-fixed-price-packages.md · decision · active · 2026-06-02 · New offers use three fixed-price packages instead of hourly billing.
L13: > New offers use three packages: Starter, Standard and Premium. No more hourly billing.
2 sectors/work/decisions/2026-08-18-no-work-on-weekends.md · decision · active · 2026-08-18 · The studio does not work or answer client messages on Saturdays and Sundays.
L11: From 2026-08-18 the studio stops working on weekends.
(5 results · terms: hour* bill* · 38 notes · fts5 · 0.04 s)
(The examples in these docs use the fictional test vault of a design studio called "Linden Studio". The output above is shortened.)
Is it working?
The memory works in the background, and it shows that it does in three places. Two of them are measured: the kit writes them itself. One is best-effort: an instruction the agent may follow or not. Which AI tool gets what is in What each AI tool gets.
At every session start in Claude Code (measured), one line from memory-kit that the agent does not have to read (it is a message of the hook, not part of the agent's context):
memory-kit: memory loaded · 34 notes · 5 sectors
In a code project with the project hooks it says memory loaded for this project (dev). When the memory did not load, the line gives the reason and tells you to run
doctor, so a broken memory no longer looks like a working one. "feedback": {"notice": false}
in memory.json turns the line off.
Under an answer that used your notes (best-effort), the agent adds one line that names them, and after it saved something, one that names the new note:
📎 memory: [[fixed-price-packages]], [[harbor-bakery]]
📎 saved: [[2026-09-29-harbor-bakery-wants-a-loyalty-card]]
The rule is step 11 of the search rules and is also in the instructions of the MCP server. It is only an instruction: an agent may leave the line out, or write one without having read a note, so neither its presence nor its absence proves anything. The record is the next part.
Any time (measured), activity shows what the agents did with the memory on this computer:
$ node system/memory.mjs activity
Memory activity on this computer · last 7 days
Last use: 4 min ago · Claude Code · saved · inbox/2026-09-29-harbor-bakery-wants-a-loyalty-card.md
Today: session starts 3 · searches 5 · notes read 2 · saved 1
Last 7 days: session starts 11 · searches 23 · notes read 9 · saved 3
Who: Claude Code 38 · claude-ai (MCP) 11 · Codex 2
Notes used most: sectors/work/clients/harbor-bakery.md 6 · sectors/work/decisions/2026-06-02-fixed-price-packages.md 4
Latest:
- 4 min ago · Claude Code · saved · inbox/2026-09-29-harbor-bakery-wants-a-loyalty-card.md
- 6 min ago · Claude Code · search · 10 results · sectors/work/clients/harbor-bakery.md
- 9 min ago · Claude Code · session start
The log stays on this computer (.memory-kit/logs/activity.jsonl; never committed, no query text). Turn it off: "feedback": {"log": false} in memory.json
(The output above is shortened.) The log behind it gets one line per session start, search, note
opened, save and error lookup, from the CLI, the project hooks and the MCP server. It stays in
.memory-kit/ on this computer, which is never committed. It holds no query text and no note
text, and it never names a note of a local sector (those are only counted). activity --json
prints the same as data.
What memory-kit never does: it never talks to the network by itself. Only git goes online, and
only where you ask for it: sync pulls and pushes your memory's own repository (autosync runs it
only when you turn it on), upgrade downloads the kit from its source, and the
update check reads the kit's version tags (when you run it, or once a day
when you turn that on). There is no telemetry.
system/tests/unit/network.test.mjs proves it on every CI
run: no module of the kit imports a network module, calls fetch or starts a download tool, and
git gets pull, push, clone and ls-remote only in those places.
See it as a graph
node system/memory.mjs graph opens your memory in the browser as a graph, like the graph view of
Obsidian: every note a dot, every link a line, coloured by sector, type or status. Click a dot to
see the note and its links, search, filter, show the local graph around one note, or drag the dots
around. It is one file on your disk (.memory-kit/graph/index.html): no server, nothing online,
and the page itself is not allowed to load or send anything but its data.
graph --live keeps it running: the graph grows as notes change, and the notes an agent uses right
now light up. Local sectors appear only with graph --local, and then the files stay in your
private folder. It stays fluid with 10 000 notes.
memory-kit MCP questions
How do I connect memory-kit to my AI tools?
You can connect it to various tools like Claude Desktop, VS Code, or Cursor by running a specific command in your vault, such as node system/memory.mjs connect claude-desktop.
What are the system requirements?
You need Node.js version 22 or newer and git installed on your system.
Can I use it on my phone?
Yes, you can read your notes on your phone via GitHub or by capturing notes into the inbox using an agent.