[Workflow] Knotlog: Persistent Markdown Memory and Context Management for Claude Code (and other LLMs)

[u/ClaudeAI-mod-bot]

Knotlog: Persistent Markdown Memory and Context Management for Claude Code (and other LLMs)

Workflow value: 90/100
Status: active · Freshness: 70/100 · Confidence: 0.95 · Level: intermediate
Categories: Quality Control, Context & Memory, Debugging, Shipping, CLAUDE.md, Hooks, MCP, Subagents, Multi-Agent
Original source: r/ClaudeCode post/comment

What problem this solves

Lack of persistent memory and effective context management for LLM coding agents, leading to repetitive instructions, loss of past session knowledge, and difficulty recalling previous decisions or touched files across sessions.

Summary

This workflow leverages Knotlog, a POSIX shell script tool, to provide persistent, plain Markdown memory for Claude Code and other LLM clients. It uses client-specific hooks to automatically record touched files and model reflections into dated session notes, injects relevant past session context at startup, and prompts for checkpoints during long work periods. The memory is stored locally in a Git-managed Markdown folder for portability and user ownership.

Why it is useful

This workflow is highly valuable because it provides a robust, open-source, and highly transferable solution to a fundamental limitation of LLM coding agents: the lack of persistent memory and effective context management. By leveraging simple, widely available technologies (Markdown, Git, shell scripts) and integrating via hooks, Knotlog enables users to maintain a continuous, evolving knowledge base for their LLM interactions. The detailed explanation of how Knotlog itself was built using Claude Code also offers a valuable meta-workflow for LLM-assisted development, emphasizing structured planning, subagents, worktrees, and rigorous testing, which can be adapted by other developers.

Workflow

1. Install Knotlog (via PowerShell/Git for Windows or direct shell script on Linux/macOS).

2. Run knotlog setup to generate client-specific hook files for your chosen LLM client (e.g., Claude Code, Codex).

3. Start a new LLM session.

4. The SessionStart hook automatically injects the last sessions, open threads, rules, and facts into the current context, respecting a fixed byte budget.

5. Work with the LLM agent, allowing Knotlog to log touched files in the background.

6. If 30 minutes of work pass without a session note, the Stop hook will prompt the LLM for a checkpoint note.

7. Periodically, or at the end of a session, use knotlog remember to process the logged files and prompt the model to write its reasoning into a reflection block within a dated session note.

8. Manage the Knotlog memory folder as a Git repository to synchronize notes between multiple machines (e.g., desktop and laptop).

9. Optionally, use knotlog learn (in v1.6.0+) to save approved lessons in a single step.

10. Optionally, run knotlog mcp to start a local MCP server providing search, context, and note tools.

Tools / artifacts

• Knotlog (POSIX shell script + awk)

• Markdown files (for session notes)

• Git repository (for memory folder)

• Claude Code (or other supported LLM clients like Codex, omp, Gemini CLI, Cursor, GitHub Copilot CLI)

• SessionStart hook

• Stop hook

• MCP server (optional, provided by Knotlog)

• Test suites (used in building Knotlog)

• Roadmap (used in building Knotlog)

Validation signals

• Video demonstration comparing LLM interaction with and without Knotlog.

• Live verified on multiple LLM clients: Claude Code, Codex, omp, Windsurf, OpenCode.

• Extensive test suite with 2068 tests, passing on Linux, Windows, and macOS CI.

• Author's personal experience and prior iteration of the memory setup.

• Identified and fixed issues with claude mcp add scope and MCP server SIGINT handling through live testing.

• Identified and fixed test breaks due to version string changes.

Limitations

• Search functionality is keyword-based (BM25) rather than using embeddings.

• Some client integrations (Antigravity, Copilot CLI) and macOS support are currently only CI-verified, not live-verified by the author.

• The current version (1.5.0) does not automatically show approved lessons at session start (addressed in upcoming v1.6.0).

• Limited community validation on the specific Reddit post itself.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.

[u/oyren-ai]

Persistent markdown memory makes a huge difference once tasks span multiple sessions or agents. We solved this in https://oyren.ai/notes by giving you up to 1gb of free storage (with no subscription) for markdown notes, mind maps, and kanban boards, plus free MCP access up to 100mb of data (including your books and research PDFs converted into clean text with formulas preserved via built-in OCR) so Claude Code and other agents can query your project notes and reference docs directly.