Mnemonica

Claude-maintained architectural memory for your codebase.

Every new chat with Claude starts from zero. On any codebase past a certain size, that means either a full re-scan before the real work can begin, or Claude working half-blind on assumptions it hasn't verified. Mnemonica gives Claude a place to keep what it has already learned about your project — architecture, ownership, the "why" behind non-obvious decisions — written incrementally as part of normal work, not as a separate documentation pass someone has to remember to run.

Why Mnemonica

• Documentation stops rotting. The usual failure mode isn't bad documentation — it's documentation nobody updates once the code moves on. Mnemonica makes updating knowledge/ part of the same edit that changes the code, with an explicit rule for fixing stale content in place, not just appending to it.

• Context survives switching chats. Open a brand-new conversation, point Claude at the project, and it already knows how two services are meant to stay in sync, why a workaround exists where an obvious fix would look simpler, which module owns which paths — the things a fresh session would otherwise have to re-derive from the code or, worse, guess. You stop paying the "catch me up" tax every time you start a new chat or hand the project to a teammate's session.

• Cheap to read, cheap to keep current. Claude reads a compact, modular index and only the file relevant to the current task — not one sprawling CLAUDE.md that grows without bound, and not a full-repo re-scan on every question. audit-light updates only what a commit actually touched; a full re-scan is there when you need it, not the default.

What it installs in a project

• knowledge/ at the project root — one Markdown file per architecturally independent system (BACKEND.md, FRONTEND.md, DATABASE.md, ...), not one per feature.
• A block in .claude/CLAUDE.md — the algorithm Claude follows to decide when a change needs a new module file versus an edit to an existing one, how to keep a module current (including fixing stale content, not just appending), how to handle changes that span multiple modules, and the index of knowledge/ files with the code paths each one owns. The block is delimited (MNEMONICA:BEGIN/END) so it installs alongside any rules the project already has in CLAUDE.md, without touching them.

Everything else about the project — README.md, existing CLAUDE.md content, the code itself — is left alone except where a skill's job is specifically to touch it.

Skills

Skill	Trigger	What it does
mnemonica:setup	"set up mnemonica", "install mnemonica in this project"	One-time install. Detects new / existing / already-managed projects and only populates knowledge/ via audit-full when that's actually needed. Also flags (without editing) any pre-existing CLAUDE.md rule that competes with Mnemonica's own "consult knowledge/ first" trigger.
mnemonica:audit-light	"run a mnemonica light audit", "quick doc sync"	Cheap, incremental. Diffs from a stored checkpoint commit to HEAD, patches only the modules whose owned paths were actually touched. Requires git.
mnemonica:audit-full	"run a mnemonica full audit", "rebuild the knowledge docs"	Full reconciliation of every module against the whole codebase. Also the engine setup uses to bootstrap an existing project. Works without git too (degraded file listing). Asks before scanning a project that turns out to be unusually large or odd-shaped.
mnemonica:status	"check mnemonica status", "is mnemonica up to date"	Read-only. Module list, index integrity, commits behind the last audit, and a brief sense of what changed recently. Never writes anything.
mnemonica:uninstall	"uninstall mnemonica", "remove mnemonica from this project"	Removes the CLAUDE.md block without touching any other content in that file; asks before deleting knowledge/.
mnemonica:brief-light	"quick project brief", "orient me on this project"	Read-only. CLAUDE.md index plus a bounded slice of each module — fast, cost stays predictable regardless of module size.
mnemonica:brief-full	"full project brief", "deep project overview"	Read-only. The complete content of every module, not a bounded slice — comprehensive, more expensive.
mnemonica:doctor	"check documentation quality", "run mnemonica doctor"	Read-only. Flags stub modules, overly broad or overlapping globs, documentation that hasn't been touched in a long time, and pre-existing CLAUDE.md rules that compete with Mnemonica's own trigger for consulting knowledge/ — quality of the docs themselves, not whether they match the code (that's audit-full's job).

All eight are invoked explicitly by a human. Nothing in Mnemonica runs automatically on a git hook, a commit, or a push.

Any invocation can carry extra wording past the trigger phrase (for example, "set up mnemonica and also use graphify for navigation") — each skill treats that as scoping or preference for the run, never as license to skip a step or bypass a rule it would otherwise follow. See the note at the top of each SKILL.md.

A day in the life

/mnemonica:setup                    # once — populates knowledge/ for an existing project

From then on, you just work. Ask Claude to fix a bug, add a route, refactor a module — as it touches code that a knowledge/ file already documents, it corrects what changed and moves on; nothing extra to run. Periodically (or after a big batch of commits), a quick

run a mnemonica light audit

catches anything that slipped through without a matching Claude session. And the part that matters most day-to-day: tomorrow, in a new chat, "help me understand how the billing webhook retries a failed charge" doesn't start with Claude reading half your server/ directory — it starts with knowledge/BILLING.md, already there, already correct.

Design conventions

The full rule set (independence test for new modules, update rules, cross-cutting-change handling, when Claude is required to ask before acting, checkpoint file format, the pre-flight size/anomaly check, .mnemonica-ignore format, git-dependency and monorepo notes) lives in references/knowledge-conventions.md and is shared by every skill — it is the one place those rules are defined, so it is the one place to change them.

Shared scripts

scripts/write-checkpoint.sh, scripts/check-index-integrity.sh, scripts/remove-mnemonica-block.sh, scripts/doc-quality-scan.sh, and scripts/lib-exclude.sh (sourced, not run directly) live at the plugin root because more than one skill depends on each and they must agree on their exact contract — see "Shared scripts" in knowledge-conventions.md. Skill-specific scripts (skills/audit-light/scripts/diff-since-checkpoint.sh, skills/audit-full/scripts/list-tracked-files.sh) stay inside their own skill.

Testing

tests/run-tests.sh

Runs the full regression suite against throwaway git repositories created with mktemp outside this repo — nothing a test run does ever touches this working tree. Covers the checkpoint-correctness scenarios (stale checkpoints via simulated squash, zero-commit repos, malformed state files), the non-git fallback, .mnemonica-ignore handling (including a metacharacter "torture test" — a real bug was found and fixed here: bash's ${var//pattern/replacement} treats a * or ? pattern as a glob, not a literal character, which silently corrupted the exclude regex until a per-character sed-based escape replaced it), the pre-flight summary's LARGE/ODD flag logic, index-integrity detection, doc-quality-scan.sh's checks, and uninstall's block removal. Requires shellcheck separately for static analysis (shellcheck scripts/*.sh skills/*/scripts/*.sh) — not run by run-tests.sh itself.

Known limitations

• Very large individual directories: the pre-flight check in audit-full (Step 1) stops and asks before scanning a project that is large or odd-shaped overall, but it reasons at the top-level-directory granularity — a single enormous flat directory with no further substructure is still one pre-flight decision, not a chance to drill down further within it. Scoping to a sub-path (one of the three choices offered) is the workaround.
• Fully git-less projects: audit-light cannot run at all without git — see "Git dependency" in knowledge-conventions.md for why a hand-rolled non-git alternative was considered and set aside rather than built.

Versioning

The plugin version lives in exactly one place: .claude-plugin/plugin.json. Individual SKILL.md files intentionally don't declare their own version — Claude Code always prefers plugin.json's value anyway, so a second copy could only ever drift and mislead, never help.

Installing locally

claude --plugin-dir /path/to/mnemonica

Then, inside a project: /mnemonica:setup.

Installing from GitHub

/plugin marketplace add HAX-Studio/mnemonica
/plugin install mnemonica@mnemonica-marketplace

License

MIT — see LICENSE.