Skip to main content
Glama
curl -fsSL https://raw.githubusercontent.com/MSelmanSonmez/Knotlog/main/install.sh | sh

Knotlog 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 quipu command is gone. If you have a vault made under the old name, run knotlog migrate to preview the changes and knotlog migrate --apply to write them; it also rewrites old quipu hook commands to knotlog. 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:

  1. Do some real work with your agent — make decisions, write notes, close a thread.

  2. Close the session. Restart the machine.

  3. 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 | sh

Windows (PowerShell, from source):

git clone https://github.com/MSelmanSonmez/Knotlog.git; cd Knotlog
.\install.ps1

macOS / Linux / Git Bash (from source):

git clone https://github.com/MSelmanSonmez/Knotlog.git && cd Knotlog
./knotlog install

Setup 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 --> A

Hooks 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 install

Verified in live sessions

Codex

adapters/codex/hooks.json, copied by hand; approve the trust prompt once

Live-verified on CLI 0.153.0 (Linux)

omp (oh-my-pi)

session_start hook, wired by install

Verified once, live

Antigravity

knotlog setup antigravity writes .agents/hooks.json (session-start context, save guard at turn end)

Covered by tests; not yet live-verified

Windsurf / Devin Desktop

knotlog setup windsurf writes .devin/hooks.json (edit capture, remember after each response; context via AGENTS.md)

Live-verified on Linux (Devin Desktop 3.11.216); Windows not verified

OpenCode

knotlog setup opencode writes .opencode/plugins/knotlog.js (edit capture, remember when idle; context via AGENTS.md)

Live-verified on Linux (OpenCode 1.19.4); Windows not verified

GitHub Copilot CLI

knotlog setup copilot writes .github/hooks/knotlog.json (session-start context, edit capture, review ask at turn end, remember at session end)

Covered by tests; not yet live-verified

Anything else (Cursor, Cline, Goose, Zed, Aider, …)

knotlog context --bridge writes memory into AGENTS.md and CLAUDE.md; Aider reads AGENTS.md only with read: AGENTS.md in .aider.conf.yml, Zed only when no other rules file (.rules, .cursorrules, …) comes first

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, kaomoji or emoji (--flair), in the install wizard or later with knotlog tone and knotlog 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.md and Facts.md are 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

knotlog doctor

check the setup: tools, agents, broken links, uncommitted memory

knotlog search <terms>

find notes (BM25, accent-folded; --tag/--status filters)

knotlog note "<text>"

add one line to today's session reflection

knotlog pending

review queued notes and proposals before they are written (notes queue when write_approval=on; propose always queues; --approve N, --reject N; --approve N --to note|facts|thread [--dry-run] picks the target; /learn in Claude Code queues a lesson)

knotlog context

print what the agent sees at session start

knotlog tui

browse the newest session notes in the terminal

knotlog plan <name> --project <Project>

open a plan note inside a project

knotlog card <name> --project <Project>

open a numbered work card (NNN-<name>.md) inside a project

knotlog board [--project <Project>] [--status <status>] [--ready]

read-only board of every work card, with a summary line

knotlog help [--<code>]

help in English, or in another shipped language with --<code> (e.g. --tr)

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
0

The 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çık and acık collapse 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

License

MIT — see LICENSE.

Available Tools

3 tools
knotlog_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).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent shared memory for AI coding agents that turns a folder of markdown files into searchable memory across sessions, repos, and machines.
      10 npm
      Functional Source , Version 1.1, MIT Future
    • F
      license
      Not graded
      quality
      C
      maintenance
      Persistent memory for AI agents enabling saving, searching, and managing knowledge across sessions with local markdown files.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      7
      1
      MIT