knotlog
This MCP server exposes Knotlog’s local vault memory for searching notes, retrieving session context, and appending session reflections.
Search notes: run folded lexical/BM25 search over Knotlog vault notes and return matching notes with short snippets; requires
query, accepts optionallimit.Get session context: return the current Knotlog vault’s session memory context with no parameters.
Append a note: add one line to today’s session reflection note, append-only, equivalent to
knotlog note, and write nothing else.
Integrates with GitHub Copilot CLI by writing hook configuration for session-start context, edit capture, review prompts at turn end, and remembering session activity at session end.
curl -fsSL https://raw.githubusercontent.com/MSelmanSonmez/Knotlog/main/install.sh | shKnotlog gives Claude Code, Codex and other coding agents a memory that outlives the session. It keeps that memory as plain Markdown in a folder you own (a vault), injects the relevant part at every session start, and never sends anything off your machine. It is a POSIX shell script: no Python, no Node, no database, no API key.
Formerly Quipu. Knotlog is the new name of Quipu; the old
quipucommand is gone. If you have a vault made under the old name, runknotlog migrateto preview the changes andknotlog migrate --applyto write them; it also rewrites oldquipuhook commands toknotlog. A bridge block you edited by hand is not refreshed (only its markers are renamed) and you get a warning.
The amnesia test
The shortest proof of what Knotlog buys you. Run it yourself:
Do some real work with your agent — make decisions, write notes, close a thread.
Close the session. Restart the machine.
Open a new session and ask one question: "What did we do yesterday?"
Without Knotlog the answer is "I have no access to previous conversations." With Knotlog the answer is your yesterday: the decisions, their reasons, and where you left off — read back from the vault, not from the model's memory.
Related MCP server: context-vault
Quick start
macOS / Linux — one line, no checkout:
curl -fsSL https://raw.githubusercontent.com/MSelmanSonmez/Knotlog/main/install.sh | shWindows (PowerShell, from source):
git clone https://github.com/MSelmanSonmez/Knotlog.git; cd Knotlog
.\install.ps1macOS / Linux / Git Bash (from source):
git clone https://github.com/MSelmanSonmez/Knotlog.git && cd Knotlog
./knotlog installSetup asks four things — language, vault location, your name, and optionally a companion name and vault purpose — then creates the vault, wires it for Claude Code and omp, and ends with one next step: open the vault folder and run knotlog doctor. That is all a new user needs.
Then read the user guide — docs/GUIDE.md (Türkçe · Español · Português · 日本語 · 简体中文) — for the daily loop and the commands you type by hand. Not sure it is for you yet? docs/WHY.md (Türkçe · Español · Português · 日本語 · 简体中文) makes the case in one read.
Using it with an existing code repository
The hooks live in the vault's .claude/settings.json, so they run only when the agent opens the vault folder. To keep the same memory while you work in another repository, leave the vault where it is and point the repository at it: copy the hooks block from adapters/claude-code.json into the repository's .claude/settings.json (or into ~/.claude/settings.json for every project) and add the vault's path:
{ "env": { "KNOTLOG_VAULT": "/path/to/your/vault" } }Every hook then reads and writes that vault, and files you edit in the repository show up under recent activity with their full paths. Running knotlog init inside the repository instead turns the repository itself into a vault, folders included.
How it works
flowchart LR
A[Agent works<br/>reads & edits files] -->|hook: capture| B[activity.log]
B -->|hook: remember| C[Session note<br/>Sessions/YYYY-MM-DD.md]
C -->|model fills<br/>reflection block| C
C -->|hook: context| D[Next session start<br/>recent work, rules, facts]
D --> AHooks record which files the agent touched, remember turns that ledger into a dated session note, and the model writes down why in a reflection block inside it. At the next session start, context injects the recent sessions, open threads, your rules and your facts — within a fixed byte budget — so the agent picks up where you left off. Knotlog keeps the mechanical record; the meaning comes from the model that is already running.
Supported agents
Agent | How Knotlog connects | Status |
Claude Code | Project-scoped hooks, wired by | Verified in live sessions |
Codex |
| Live-verified on CLI 0.153.0 (Linux) |
omp (oh-my-pi) |
| Verified once, live |
Antigravity |
| Covered by tests; not yet live-verified |
Windsurf / Devin Desktop |
| Live-verified on Linux (Devin Desktop 3.11.216); Windows not verified |
OpenCode |
| Live-verified on Linux (OpenCode 1.19.4); Windows not verified |
GitHub Copilot CLI |
| Covered by tests; not yet live-verified |
Anything else (Cursor, Cline, Goose, Zed, Aider, …) |
| No hooks needed |
Claude Code reads CLAUDE.md, most other agents read AGENTS.md; Knotlog writes the same memory to both, so work done in one agent reaches the other. Details per adapter: docs/REFERENCE.md.
Why Knotlog
Zero dependencies: POSIX sh + sed + awk + grep + tr + git only (no Python, Node, jq).
100% offline, free: nothing leaves your machine, no API keys. The context goes in once per session (4 KB cap by default); each prompt adds only a one-line clock.
Cross-platform: Windows, macOS, Linux — CI-verified on all three.
Multilingual: the interface ships in six languages (English, Türkçe, Español, Português (Brazil), 日本語, 简体中文). Pick one with
--lang <code>(en,tr,es,pt-br,ja,zh-cn),lang=in the config, or the install wizard. English and Turkish are maintained by hand; the other translations are machine-assisted, and corrections are welcome.Reply style: pick a tone preset (
--tone) and an optional flair,none,kaomojioremoji(--flair), in the install wizard or later withknotlog toneandknotlog flair.Storage: plain Markdown, no database — your files, no lock-in.
Secret gate, on by default: the vault is a git repository with a pre-commit scanner that rejects a commit carrying a known secret shape.
A behavior contract, not just notes:
Rules.mdandFacts.mdare injected at every session start — a correction you write once holds in the next session instead of being repeated.
Why free where competitors charge for infrastructure: tools like claude-mem need a separate vector database and AI worker because their worker is a separate process with no model inside. Knotlog has no such problem — the agent is already running and paid for, so the semantic layer is the model itself.
Commands
The ones you will actually type; the full table is in docs/REFERENCE.md.
Command | What it does |
| check the setup: tools, agents, broken links, uncommitted memory |
| find notes (BM25, accent-folded; |
| add one line to today's session reflection |
| review queued notes and proposals before they are written (notes queue when |
| print what the agent sees at session start |
| browse the newest session notes in the terminal |
| open a plan note inside a project |
| open a numbered work card ( |
| read-only board of every work card, with a summary line |
| help in English, or in another shipped language with |
A first session
A first session, end to end:
$ knotlog init
knotlog vault initialized: <vault>
layout: emoji
AGENTS.md bridge block ensured
companion.md seeded
Rules.md seeded
Facts.md seeded
next: knotlog index
Secret gate not installed: the vault is not a git repository root — run git init, then knotlog init again
$ printf '# Work note\n\nAbout Istanbul.\n' > note.md
$ knotlog index
# indexed 6 (reused 0, stale 6, dropped 0)
$ knotlog search work --paths
Rules.md
Facts.md
🔮 850-Companion/companion.md
note.md
$ knotlog context --json SessionStart
{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"…"}}
$ knotlog doctor; echo $?
summary: 157 ok, 3 warn, 0 fail
0The seeded Rules.md, Facts.md, and companion.md are ordinary notes and get
indexed like any other, which is why a broad query returns them alongside your
own — narrow the terms, or filter with --tag/--status. The secret-gate line
is the last thing init prints: it installs .githooks/pre-commit when the
vault is a git repository root, and says so when it is not.
Pass --lang <code> to init (e.g. --lang tr) for output in another language.
FAQ
No. Knotlog reads and writes files in your vault and runs no server. The only commands that touch the network are the installer and knotlog update, which talk to GitHub. What Knotlog injects into a session is then sent to your agent's model provider, like everything else in that session — that part is governed by your provider's data policy.
No. Knotlog writes only inside its own marker blocks (<!-- knotlog:start --> … <!-- knotlog:end -->); everything outside them is yours and is never touched. If your .claude/settings.json already differs from Knotlog's adapter, install keeps your file byte for byte and tells you what to merge.
Claude Code: its adapter is verified against live sessions and install wires it for you. Codex works after you copy one file and approve its trust prompt once. Any other agent can use the hook-less bridge, and any MCP client can search the vault through knotlog mcp (tools knotlog_search, knotlog_context and knotlog_note). See Supported agents.
Yes. Install from PowerShell with .\install.ps1; it needs Git for Windows and no administrator rights. The test suite runs on Windows, macOS and Linux in CI, and a real end-to-end install has been done on Windows and Linux. macOS is CI-verified only so far.
knotlog uninstall --dry-run shows what would go, knotlog uninstall removes the command (on Windows, .\uninstall.ps1). Your vault is never deleted — those are your notes. See Uninstall.
There is no embedding step and no second model. Knotlog does fast lexical search (BM25 over accent-folded text) and leaves judgement to the agent that is already in the loop. That is better on meaning but weaker on exhaustive recall — see the limits below.
Honest limits
Folding is lossy:
açıkandacıkcollapse together — a deliberate trade-off."Semantic" ≠ cosine similarity: model judgment, better on meaning but weaker on exhaustive recall.
Index context limit: comfortable up to a few thousand notes; beyond that, narrow first with
search --brief.macOS is CI-verified, not yet installed live; if something is off there, that is a report worth filing.
Notes are framed, not sandboxed: context marks your notes as information, not instructions, yet a model can still be swayed by text an agent once wrote into them; glance at what lands in
Threads.md.
The complete list, including what each adapter does not capture, is in docs/REFERENCE.md.
Documentation
User guide (Türkçe · Español · Português · 日本語 · 简体中文) — the daily loop, the folders, the commands you type by hand.
Why Knotlog (Türkçe · Español · Português · 日本語 · 简体中文) — the case for it in one read.
Reference — install internals, every command, each adapter, vault layout, search, update and rollback.
Usage runbook — step-by-step setup written for a coding agent to follow; locked by tests, so it cannot drift from the real command surface.
Stability — what stays stable across 1.x, what may change, and how breaking changes are announced.
License
MIT — see LICENSE.
Available Tools
3 toolsknotlog_contextC
Return the session memory context of the current Knotlog vault.
knotlog_noteA
Append one line to today's session reflection note in the Knotlog vault (append-only, the same as knotlog note); writes nothing else.
Inputs: text (required).
knotlog_searchB
Search the Knotlog vault notes (folded lexical plus BM25 ranking); returns matching notes with short snippets.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools target clearly distinct operations: reading session context, appending a note line, and searching the vault. While context and search both retrieve information, their scope (session memory vs. lexical/BM25 vault search) is clearly stated. No plausible misselection between them.
All tools share the consistent `knotlog_` prefix, giving a predictable namespace. The suffixes mix nouns (context, note) with a verb (search), and the noun-style names are slightly ambiguous as to read vs. write, but the overall pattern holds.
Three tools is thin for a note/vault server, especially since retrieval is split between context and search while no tool fetches a full note. The set is minimal but leans toward under-scoped rather than well-scoped.
Core read/append/search workflows exist, and append-only writing appears intentional. However, there is no way to fetch a full note (search returns only snippets), list notes, or correct/delete an entry, which are notable gaps for a note-management domain.
Maintenance
Related MCP Connectors
Cross-session, cross-device memory for your agent: remember and recall notes. No key to start.
Persistent memory for AI agents: save, search and connect context across tools and sessions.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenancePersistent shared memory for AI coding agents that turns a folder of markdown files into searchable memory across sessions, repos, and machines.10 npmFunctional Source , Version 1.1, MIT Future
- FlicenseNot gradedqualityCmaintenancePersistent memory for AI agents enabling saving, searching, and managing knowledge across sessions with local markdown files.-
- AlicenseNot gradedqualityDmaintenanceProvides persistent, local-first memory for coding agents with Markdown as the source of truth, exposed via CLI, loopback API, MCP, and Codex hooks for context retrieval and durable writes.MIT
- AlicenseAqualityBmaintenanceProvides AI coding assistants persistent engineering memory stored as Markdown files in an Obsidian vault, enabling project context retrieval, session capture, decision recording, and memory search without requiring Obsidian to be running.71MIT