{"slug": "show-hn-directed-memory-bank-tool-agnostic-project-context-for-ai-agents", "title": "Show HN: Directed Memory Bank – Tool-agnostic project context for AI agents", "summary": "Directed Memory Bank (DMB) is a tool-agnostic, markdown-based framework that gives AI coding agents persistent project context, eliminating the need to re-explain the stack, auth flow, and constraints at the start of every session. The system works with Claude Code, Cursor, Gemini, Codex, or any LLM-based agent that can read files, and stores structured project knowledge in plain markdown files under a `memory-bank/` directory. DMB solves context loss, irrelevant AI suggestions, vanishing discoveries, tool fragmentation, and decaying decision rationale without requiring a server, build step, or vendor lock-in.", "body_md": "**Persistent project understanding for AI coding agents.**\n\nYour AI agent starts every session knowing nothing. **Directed Memory Bank (DMB)** gives it structured project knowledge and working state — in plain markdown files that work with any tool.\n\nInspired by the\n\n[Cline Memory Bank pattern]. See[Inspiration]below.\n\nYou know the ritual. Coming back after the weekend, you open a new AI session and burn the first ten minutes re-explaining the stack, the auth flow, the deprecation plan, why library X is off the table — before you can finally ask the actual question. With DMB, that ritual is gone. The AI already knows the project. You just continue.\n\nConcretely:\n\n**Sessions resume, they don't restart.** Open a new Claude Code or Cursor session and your project context is already in scope. The AI doesn't need to be re-introduced to the codebase before it can help.**Switching tools costs nothing.** Start a refactor in Claude Code, finish it in Cursor. Both read the same`memory-bank/`\n\nfiles; both are on the same page about your stack and your conventions.**AI recommendations match your team, not the internet.** The model stops suggesting Redis when`technical/stack.md`\n\nsays you've standardised on Postgres-as-cache. Stops suggesting NestJS when you've committed to FastAPI. Decisions you made once stay made.**Knowledge survives turnover.** When a teammate leaves, their understanding of the system doesn't leave with them. The*\"why we built it this way\"*lives in`technical/architecture.md`\n\nnext to the decision, not in a Slack thread from eight months ago.**Cross-session memory of in-flight work.** You paused a feature to handle an urgent bug. A week later you pick it back up — the AI knows where you left off, what's still open, what was decided. That's`tasks/work/<slug>.md`\n\ndoing its job.\n\n**Context loss**— stop re-explaining your project every session.** AI suggestions miss the mark**— stop fighting recommendations that ignore your team's actual decisions.** Discoveries vanish**— stop losing things you noticed during focused work.** Tool fragmentation**— stop duplicating conventions across Claude, Cursor, Gemini configs.** Decision rationale decays**— stop wondering*\"why was this done this way?\"*months later.\n\nA file convention. No server, no build step, no lock-in. Just markdown files organised so AI agents find what they need, when they need it.\n\n**Tool-agnostic** — works with Claude Code, Cursor, Gemini, Codex, or any LLM-based agent that can read files.\n\n**Adopt what you need** — the knowledge layer and RAM layer are independently valuable. Use the full framework or just the parts that solve your problem.\n\nTwo angles. First — what your day looks like with DMB vs without. Second — where DMB sits next to context tools you might already use.\n\n| Without DMB | With DMB | |\n|---|---|---|\n| Start a new AI session | Re-explain the stack, the auth flow, the constraints (5–15 min) | Project context already in scope |\n| Switch from Claude Code to Cursor mid-task | Rebuild context in the new tool | Both tools read the same `memory-bank/` files |\n| A teammate leaves | Their understanding leaves with them | The \"why\" lives in `technical/architecture.md` |\n| AI suggests a library | Whatever's most common in training data | What `technical/stack.md` says you actually use |\n| Bot writes to a PR log | Merge conflicts with humans appending to a shared file | Bot writes its own file in `tasks/log/` |\n| Pick up a paused feature two weeks later | \"Wait, what did I decide about X?\" |\nRead `tasks/work/<slug>.md` and continue |\n\nSingle `CLAUDE.md` / Cursor rules / `AGENTS.md` |\nTool's built-in auto-memory | MCP memory servers (mem0, Letta, …) | DMB | |\n|---|---|---|---|---|\n| Works across AI tools | No — one tool only | No — per-user, per-tool | Partial — depends on MCP support | Yes — every tool that reads files |\n| Lives in version control | Yes | No | No (in server) | Yes |\n| Scales past one big file | No — gets bloated | N/A | Yes | Yes — split by rate of change |\n| Operation-scoped loading | No | No | Tool-dependent | Yes — integration layer routes by intent |\n| Multi-writer safe (humans + bots) | No — append conflicts | No | Limited | Yes — file-per-item |\n| No runtime dependency | Yes | Yes (tool only) | No — needs server | Yes |\n\nDMB doesn't replace any of these. It composes with them: a thin `CLAUDE.md`\n\nor Cursor rule references DMB; the tool's auto-memory still captures personal preferences; if you run an MCP memory server, your DMB files can be exposed through it.\n\nKarpathy recently described an [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — same intellectual lineage (file-based markdown, LLM as maintainer, Memex-style associative knowledge) applied to *knowledge accumulation*: research notes, book companions, due diligence, team wikis fed by Slack and meeting transcripts.\n\nDMB applies the substrate to *code project context*. Different problem, different design choices: the codebase is the source of truth (no \"raw sources\" layer to ingest); file-per-PR log instead of single append-only `log.md`\n\nso humans + CI bots can write concurrently; a separate integration layer so the same `memory-bank/`\n\nworks across Claude Code, Cursor, Gemini and others; a knowledge/RAM split so in-flight work persists across sessions.\n\nComplementary, not competing. A real team can run both — Karpathy-shaped wiki for research/spikes; DMB for the repo they ship from. When a spike concludes, the locked-in tech decision graduates from the wiki into `memory-bank/technical/stack.md`\n\n.\n\nA few trends make a file-based context layer genuinely important in 2026:\n\n**Context protocols are converging**— Claude Code skills, Cursor rules, Codex Agent Skills, Gemini CLI hooks, MCP servers all assume a readable project knowledge layer exists. DMB gives you one that every tool understands.**AI teams are multi-writer**— humans*and*automations write project state now (progress logs, PR status, observability feedback). The standard is designed so multiple writers can coexist without constant merge conflicts.**Agentic CI is rising**— LLM-as-reviewer, spec-driven engineering, autonomous triage bots. All of them benefit from a structured, queryable project context they can read and, carefully, write.\n\nThe standard stays simple (markdown, no tooling). It just pays close attention to the seams where humans and automations meet.\n\n-\n**Scaffold DMB in your project:**\n\n```\nnpx directed-memory-bank init\n```\n\nNo Node? Clone and copy manually:\n\n```\ngit clone https://github.com/pmikutel/directed-memory-bank.git\ncp -r directed-memory-bank/template/memory-bank/ your-project/memory-bank/\n```\n\n-\n**Open your AI tool of choice**(Claude Code / Cursor / Codex / Gemini)** in your project, and say:**\"Follow memory-bank/INSTALL.md to set up my DMB.\"\n\n-\n**Answer the questions.** Skip what you're not ready for, paste docs instead of typing where you can. Your progress is tracked in`memory-bank/_adoption.md`\n\n— come back any time and say*\"continue DMB install\"*; your AI will pick up where you left off.\n\nThat's it. For more depth see [docs/](/pmikutel/directed-memory-bank/blob/main/docs).\n\n`_index.md`\n\ncatalogs what's in `memory-bank/`\n\nand which files matter for each kind of work — development, debugging, deployment, etc. It plays three roles:\n\n**Inventory**— humans and AI agents browsing DMB read it to navigate.** Authoring source-of-truth for the integration layer**— when you (or an AI agent acting on your behalf) create or update a Claude Code skill, a Cursor rule, a hook, or any other per-tool integration artefact, you read`_index.md`\n\nfirst to see which memory-bank files matter for the operation. The integration-layer file then references those memory-bank files directly.**Fallback runtime router**— for tools without skills, hooks, or path-scoped rules (Codex, Gemini CLI, custom agents),`_index.md`\n\ncan be loaded as the runtime routing table.\n\nFor tools with strong harness mechanisms, the integration layer is where routing happens — skills, hooks, and rules name the memory-bank files directly. `_index.md`\n\nkeeps them coherent without standing between them and the knowledge at runtime.\n\n| Layer | What | Changes | Optional? |\n|---|---|---|---|\nKnowledge |\nArchitecture, domain, conventions, stack decisions | Slowly — when project evolves | Core |\nRAM |\nCurrent focus, in-flight topics, completed-work log | Every session | Yes |\n\nDMB is one of three destinations for documentation. The split:\n\n| Reader | Destination |\n|---|---|\n| AI agent writing code in this repo | `memory-bank/` |\n| Teammate understanding architecture / current work | `memory-bank/` |\n| Dev setting up / running locally | `README.md` (per package) |\n| Reader outside the code work (other team, external consumer) | external-docs folder (your choice of name) |\n\nThe resolving test: **\"Would I want an AI agent to load this file while writing / reviewing / debugging code in this repo?\"** Yes → memory-bank. No → external-docs. Unsure → memory-bank (the default).\n\nFull guide: [docs/what-goes-where.md](/pmikutel/directed-memory-bank/blob/main/docs/what-goes-where.md).\n\nDMB lives in two destinations inside your repo:\n\n| Destination | Where | What it holds |\n|---|---|---|\n`memory-bank/` |\nIn your repo | Tool-agnostic project truth — domain, architecture, conventions, in-flight scratchpads |\nIntegration files |\n`.claude/` , `.cursor/rules/` , `GEMINI.md` , `AGENTS.md` , etc. |\nPer-tool wiring — skills, rules, hooks, instruction files that reference memory-bank/ |\n\nPlus your tool's auto-memory, which holds personal preferences (terse-vs-verbose, workflow tweaks) — managed by the tool, never committed, out of DMB's scope.\n\nVisualised:\n\n```\n   Claude Code      Cursor       Codex / Gemini / others\n        │             │                │\n        ▼             ▼                ▼\n   ┌──────────────────────────────────────────┐\n   │ Integration files (per-tool, in repo)    │\n   │ .claude/skills/, .cursor/rules/,         │\n   │ CLAUDE.md, GEMINI.md, AGENTS.md          │\n   └──────────────────┬───────────────────────┘\n                      │ references files in\n                      ▼\n   ┌──────────────────────────────────────────┐\n   │ memory-bank/  (in repo, tool-agnostic)   │\n   │                                          │\n   │  ┌──────────────┐ ┌────────────────────┐ │\n   │  │ Knowledge    │ │ RAM                │ │\n   │  │ project/     │ │ tasks/work/        │ │\n   │  │ technical/   │ │ tasks/log/         │ │\n   │  └──────────────┘ └────────────────────┘ │\n   │                                          │\n   │  _index.md — inventory of what's in here │\n   └──────────────────────────────────────────┘\n```\n\nYour AI tools stay unchanged at the top. Per-tool integration files are the only thing you write per-tool — and they're thin pointers. `memory-bank/`\n\nis the shared store every tool reads.\n\n**The principle for the integration layer: use what works today.** Every modern AI tool offers more than one mechanism for hooking into context (instruction files, path-scoped rules, skills, hooks, MCP servers, …). For each tool, lead with the mechanism that is most reliable today. Demote the less-reliable ones to lower-stakes routing. Rebalance as the tools evolve.\n\n`memory-bank/`\n\nnever moves. Starter templates for Claude Code, Cursor, Codex CLI, and Gemini CLI demonstrate the principle today — each with a per-tool tier ladder (hooks, skills / rules, instruction files). Use them as starting points and adapt as the tools change.Deep dive — including per-tool starter ladders and concrete file shapes: [docs/integration-architecture.md](/pmikutel/directed-memory-bank/blob/main/docs/integration-architecture.md).\n\nAfter install, your `memory-bank/`\n\nlooks like this:\n\n```\nmemory-bank/\n├── _index.md                  # Inventory — what files exist, when each is relevant\n├── INSTALL.md                 # AI-driven install interview (delete or keep after install)\n├── _adoption.md               # Install progress tracker (created during install)\n│\n├── project/                   # Project identity (slow-changing)\n│   ├── brief.md               # 30-second overview — always loaded\n│   ├── domain.md              # Business entities, rules, workflows\n│   ├── vision.md              # Problem space, long-term goals (optional)\n│   └── doc-guide.md           # Style, length & hygiene rules — loaded on every memory-bank write\n│\n├── technical/                 # Technical knowledge (medium-changing)\n│   ├── stack.md               # Tech stack, key decisions, gotchas\n│   ├── architecture.md        # System design, patterns, data flow\n│   └── [topic].md             # Add as needed: auth.md, api.md, deployment.md\n│\n└── tasks/                     # RAM — fast-changing, optional\n    ├── process.md             # How to maintain work/ and log/\n    ├── work/                  # One file per topic — idea, in-flight, draft spec\n    └── log/                   # One file per merged PR (typically written by automation)\n```\n\nOnce multiple writers are involved (humans plus CI automations plus LLM assistants), append-to-single-file patterns break. DMB is deliberately designed so every write targets a unique file owned by exactly one writer at any moment.\n\nIf you want to wire up bot-driven writes to `tasks/work/`\n\nand `tasks/log/`\n\non CI events, see [docs/automation-patterns.md](/pmikutel/directed-memory-bank/blob/main/docs/automation-patterns.md) for the reference pattern (branch-name matching, bot identity scoping, loop prevention) and the [complete example](/pmikutel/directed-memory-bank/blob/main/examples/complete) for a worked instance with an illustrative GitHub Actions archiver.\n\nAutomation is entirely opt-in. The standard works fully by hand.\n\n— 4 files, no RAM layer. The bare minimum floor, shown with a small real project (TinyLink).[minimal/](/pmikutel/directed-memory-bank/blob/main/examples/minimal)— A fully-filled DMB end-to-end: knowledge layer ([complete/](/pmikutel/directed-memory-bank/blob/main/examples/complete)`project/`\n\n+`technical/`\n\n)*plus*the`tasks/`\n\nRAM layer (populated`work/`\n\n+`log/`\n\n)*plus*an optional, illustrative GitHub Actions archiver — all on a fictional book-tracking app. Shape and depth reference, not a starting point.\n\nIf you're already using DMB with `activeContext.md`\n\n/ `progressLog.md`\n\n/ `backlog.md`\n\nsingle-file appends, see [MIGRATION.md](/pmikutel/directed-memory-bank/blob/main/MIGRATION.md) for the one-off transition to `work/`\n\n+ `log/`\n\n.\n\nSee [docs/faq.md](/pmikutel/directed-memory-bank/blob/main/docs/faq.md) for common questions including:\n\n- How is this different from CLAUDE.md?\n- How is this related to the Cline Memory Bank?\n- Do I need the RAM layer?\n- Do I need\n`tasks/work/`\n\nfor every feature? - Where do docs for external readers go?\n- Hook, skill, or instruction file — which should I use?\n- How do I keep it up to date?\n- Won't AI tools make this obsolete?\n\nDMB is inspired by the [Cline Memory Bank pattern](https://docs.cline.bot/prompting/cline-memory-bank), which established the core idea: a small set of structured markdown files in the project, read by an AI agent at session start, gives the agent persistent context across sessions. Thanks to the Cline team for popularising the pattern.\n\nMIT", "url": "https://wpnews.pro/news/show-hn-directed-memory-bank-tool-agnostic-project-context-for-ai-agents", "canonical_source": "https://github.com/pmikutel/directed-memory-bank", "published_at": "2026-07-27 16:45:53+00:00", "updated_at": "2026-07-27 16:52:30.349199+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "artificial-intelligence", "large-language-models"], "entities": ["Directed Memory Bank", "Claude Code", "Cursor", "Gemini", "Codex", "Postgres", "FastAPI", "NestJS"], "alternates": {"html": "https://wpnews.pro/news/show-hn-directed-memory-bank-tool-agnostic-project-context-for-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-directed-memory-bank-tool-agnostic-project-context-for-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-directed-memory-bank-tool-agnostic-project-context-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-directed-memory-bank-tool-agnostic-project-context-for-ai-agents.jsonld"}}