mnemonic

The anti-vibe coding AI tool built for experienced engineers.

mnemonic is a single-user, self-hosted coordination plane for LLM coding agents. Its core thesis: agent sessions are temporary, failure-prone, and locally smart but globally blind. Durable work should live in a work graph that survives sessions, rather than in Markdown scratch files, suggested task chips, or an issue tracker flooded with AI-generated tickets. With a strong human-in-the-loop philosophy, it is designed to increase the code quality and throughput of experienced developers building with AI, rather than replace their thinking.

Additionally, mnemonic maintains a knowledge graph containing a versioned history of decisions made by both the human operator and agents. When a decision changes, any previously written code that was downstream of those decision is automatically discoverable. No more "grepping and hoping" when product requirements shift, even on a large codebase.

Tested with Claude Code, OpenAI Codex, and OpenCode. Probably works with any similar platform with a MCP client (Cursor, etc). It is designed for a single, local (human) user and supports multiple, concurrent development projects.

Tech stack

Is mnemonic right for your project?

• You build with Claude Code, OpenAI Codex, OpenCode and/or similar MCP client and, optionally, would like for them to coordinate work across platforms.

• Important FYIs and follow-up tasks are getting overlooked because they're buried under verbose LLM output.

• Dozens of transient Markdown documents are cluttering your repo. Or, your issue tracker has so many AI-written issues that it's become nearly unusable.

• You struggle to mentally hold onto the big picture of what your AI agents are building and why.

• Concurrent agents occasionally cause merge conflicts or reduplicate work, slowing progress and wasting tokens.

• You don't want the complexity of a full orchestration platform like OpenClaw and/or prefer a strong human-in-the-loop workflow.

Why it might not be right for you

• The human is the harness. mnemonic requires an attentive human operator. Work is delegated out to agents by manually copying and pasting pre-written prompts into your MCP client/IDE and you have to be willing to be a part of the decision loop. If vibe coding is more your speed, where you're comfortable with nearly all decisions being made by the clankers, then mnemonic is going to feel like a lot of work. The upside though, is that you understand what's being built and why and you use your existing Claude Code/Codex/OpenCode, et al UI/TUI rather than an unobservable, headless harness.

• It's not exactly lightweight. mnemonic imports, normalizes, and indexes agent transcripts and creates embeddings of the text. This doesn't require a GPU, but it's not likely to run well on a Raspberry Pi and can consume quite a bit (tens of GB) of diskspace. Plus the Docker Compose stack is 6-7 containers (depending on your config). And: the dashboard UX take a while fully master and there are over 60+ MCP tools. mnemonic was designed to help bring engineering rigor to AI-enabled development workflows but doesn't pretend that cost is free. It's a tool for experienced developers.

• mnemonic is overkill if you only run one session at a time. The platform was designed (and has been tested) to juggle 3 to 15 concurrent agents. It will dramatically accelerate work throughput at that scale. However, the operational overhead of the MCP tool calls will nerf efficiency gains if you routinely use it with only one or two simultaneous sessions.

Basic concepts

The included agent skills encourage the LLM to default to using mnemonic to save hand-off prompts and self-discovered follow-up tasks, rather than your bug/issue tracker, Markdown docs, or ephemeral "Suggested task chips".

Upon discovering something worth doing, but is out-of-scope of the current task, the agent will first search mnemonic for related work items using sophisticated full-text matching. If no matches are found, the agent opens a new Pending work item in the mnemonic dashboard -- where it waits until you tell Claude Code/Codex/OpenCode, etc. to pick it up and get to work.

Just copy-and-paste the prompt

When you decide to have your agent work on the task, you click the "Copy recall pointer" button of the task card and paste the copied prompt into a fresh session and... that's pretty much it. Everything else happens automatically.

The LLM will then start a new session, retrieve the work item, and validate the stated premises. If the facts check-out, it requests a temporary "work lease" and then begins working. The lease is periodically renewed until the task is complete and then work item is marked as Done. If the agent dies before completing the task, the lease expires and another session can pick it up again. A healthy agent though will periodically update the task with detailed checkpoints and, optionally, request a code review once done.

"I need a human!"

The human-required copy-and-paste step is deliberate. It allows you to balance your weekly usage quota or API costs between your normal development work and working through the mnemonic backlog. And it keeps you working inside your already familiar UI.

If an agent hits a blocker that needs a human-needed decision, the work is parked in Needs Attention and returns only after you record an answer in the dashboard. These decisions are recorded and become Product Decision Records (PDRs) in the project knowledge graph (see "Project-scoped knowledge graph", below).

For non-blocking FYIs, the "Summaries" list contain simplified, plain-language descriptions of what the agent accomplished once it marks a work item as done.

Other key features

- Project-scoped knowledge graph -- Decisions (both human and clanker) are recorded in Markdown decision documents that are centralized, versioned, and saved in the database. Every PR and work item cites the decisions it relied upon when authoring code. This allows you (and agents) to bidirectionally trace the provenance of decisions up and down the graph:

- "What information did the agent rely upon to decide to implement X instead of Y here?" - "If I were to change my mind and decide this app needed to support multiple users, what downstream parts of the architecture needs to be revisited?"

This feature is especially handy to precisely determine the blast radius of a mistake made dozens of PRs or weeks earlier.

- Code review hand-offs -- Projects can also require or invite an adversarial code review at configurable priority thresholds (both default to Never). Reviewers lease the original Done item and perform either a warm or cold code review. See code reviews for the complete workflow.

• Cross-platform coordination -- Claude Code, OpenAI Codex, OpenCode, et al. can all be used simultaneously in the same project and intelligently coordinate amongst themselves.

• Plain English work summaries -- The "Summaries" inbox provides an easy-to-read, durable record of what each session did so you don't have to slog through every dense transcript.

• External trackers and duplicate comparison -- Automatically finds duplicate tasks in your repo's GitHub Issues (or similar) and includes them by reference. Mitigates two, conflicting homes for agent-to-agent coordination.

• Project artifact library -- Some content shouldn't be committed in your repo (docs with PII, large binaries, etc). The project artifact library allows both agents and humans to upload, download, search, and reference these files stored in your local filesystem. The artifact library is a lightweight alternative to a traditional document management system (DMS) and can be optionally disabled in the project environment.

• Session transcript archival -- Once an agent transitions a work item to Done, mnemonic copies that transcript (and any subagent transcripts) into the mnemonic project store. Each transcript is normalized to a common, cross-vendor format and indexed. This allows Codex agents to search and read Claude Code agents' past work activity and vice versa.

• Unified search -- Agents can search across work items, artifacts, decision documents, and session transcripts to retrieve relevant information in one-shot, with results being ranked using an intelligent, composite score. This saves time, tokens, and agent context space. This hybrid search is powered by a combination of Apache Tika, Tantivy, and embeddings for semantic search.

Run it

Copy and paste into your LLM to have it handle this part.

Install and configure mnemonic for me using a published versioned release bundle from https://github.com/RightBrain-Networks/mnemonic/releases. Follow docs/releases.md and docs/operations.md for that release. Use the default local-only Docker Compose configuration unless I state otherwise, preserve any existing data and configuration, connect my MCP-capable LLM client if one is available, and continue until the documented acceptance checks pass or you need a specific decision or credential from me. If no release is available, explain that before using the contributor build instructions in AGENT-README.md.

Or, if you prefer, old school human instructions...

Requirements: Docker with Linux containers and Docker Compose v2 (docker compose). The commands below use a POSIX shell, such as Linux, macOS, or WSL. Published-image installation needs no host Python, Node, application environment, or source build.

For a published release that includes an install bundle, download its mnemonic-X.Y.Z.tar.gz and checksum from GitHub Releases, verify the checksum, and extract it. From the extracted directory, run the following, replacing X.Y.Z with that same published version:

docker run --rm --pull always --user "$(id -u):$(id -g)" \
  --mount "type=bind,source=$(pwd),target=/release" --entrypoint python \
  ghcr.io/rightbrain-networks/mnemonic-api:X.Y.Z /release/setup.py
docker compose config --quiet
docker compose pull
docker compose up -d --wait

The first command runs setup inside the selected API image and creates a private .env owned by your host user, without sudo. It does not start the application. If Python 3.10 or newer is already installed, python3 setup.py is an optional replacement for that first command. Existing .env files remain unchanged.

Use an actually published release and its matching bundle; a version mentioned on main does not imply that its images are available. Until that release is published, or when working on the source, use the contributor overlay:

git clone https://github.com/RightBrain-Networks/mnemonic.git
cd mnemonic
python3 scripts/setup.py
docker compose -f compose.yaml -f compose.build.yaml config --quiet
docker compose -f compose.yaml -f compose.build.yaml up --build -d --wait

New setup files select private named volumes. The one-shot init-storage container prepares them for the configured service UID/GID without host sudo commands; migrate initializes the database before API and worker startup. Keep the same Compose project name for later runs. The source overlay builds images with local names, separate from published release tags.

For transcript capture, add --transcript-source /absolute/claude/projects, --codex-source /absolute/codex/sessions, or --codex-archived-source /absolute/codex/archived_sessions to the setup command before creating .env. When running setup in Docker, also mount each chosen source read-only at its identical absolute path in that setup container, using --mount type=bind,source=/absolute/source,target=/absolute/source,readonly before the image name. Alternatively, run the setup command with host Python 3.10 or newer. Use only existing operator-approved directories. The helper selects their owner's UID/GID, and API and worker read those paths through read-only binds. Docker Desktop must be allowed to share configured source directories. Without sources, capture stays disabled. See transcript setup.

Existing installs: setup leaves .env unchanged. Legacy bind installations must preserve all old storage paths and use -f compose.yaml -f compose.bind-mounts.yaml on every Compose command, adding the build or TLS overlay when needed. Existing named-volume installations retain their volumes and Compose project name without the bind overlay. Base Compose intentionally refuses an implicit legacy storage mode. Follow Upgrade from any release before starting new images against existing data. That procedure stops old writers and backs up before migration.

sh ./up_mnemonic.sh starts published images with the TLS allowlists from compose.tls.yaml; use it only after configuring MNEMONIC_TLS_HOST and the nginx TLS proxy. Existing bind installs and contributor builds should use explicit -f arguments for all their overlays.

On macOS/Linux the Python command may be python3; use python where that is Python 3. Alternatively, copy .env.example to .env and supply four independent random secrets: URL-safe POSTGRES_PASSWORD and MNEMONIC_RABBITMQ_PASSWORD, plus MNEMONIC_API_KEY and MNEMONIC_BACKUP_TOKEN of at least 32 characters each. The example contains no usable credentials. Keep .env private (chmod 600 .env on POSIX systems), and never commit it. New configurations use UTC for dashboard times; explicit existing TIMEZONE values are preserved.

Open mnemonic. Create your first project using the project selector, then connect your agent to create or continue durable work. The application starts empty; there are no fabricated objectives, checkpoints, or session IDs.

| Service | .env variable | Default local address | | ---------------------- | ------------------- | ------------------------------------------------- | | Dashboard | MNEMONIC_WEB_PORT | localhost:3000 | | REST API documentation | MNEMONIC_API_PORT | localhost:8000/docs | | MCP Streamable HTTP | MNEMONIC_MCP_PORT | http://127.0.0.1:8001/mcp |

Those addresses are defaults, not fixed values. Each port is set in .env, so change one there if it collides with something already running on the host, and substitute your own value wherever this README shows a port. If the web port changes, update MNEMONIC_DASHBOARD_ORIGINS to match both http://localhost: and http://127.0.0.1:.

Run the read-only stack check inside the installed MCP container, which supplies the required Python dependencies and API key. These service addresses use internal ports even when host ports have changed; retain your installation's Compose overlays:

docker compose exec -T mcp python - \
  --api-url http://api:8000 \
  --mcp-url http://mcp:8001/mcp \
  --web-url http://web:3000 --web-origin http://localhost:3000 < scripts/check-stack.py

Set --web-origin to a dashboard origin configured in MNEMONIC_DASHBOARD_ORIGINS; substitute the actual port or HTTPS origin when using changed ports or TLS. Do not add --project-id to an installation check; that enables durable test mutations in the named project. See docs/development.md for disposable test usage.

The seven running services are postgres, rabbitmq, api, tika, mcp, web, and worker; one-shot init-storage and migrate services complete before application startup; the shared worker handles background jobs and project backups. PostgreSQL, RabbitMQ, Tika, and the worker have no published ports. Dashboard, REST, and MCP ports bind to loopback only. For LAN access through your existing nginx TLS proxy, use the nginx configuration and setup guide.

Connect Claude Code

Set MNEMONIC_API_KEY in the terminal environment to the key from your private .env file. Set MNEMONIC_MCP_PORT as well if you changed it from the default. Then register the HTTP MCP endpoint:

claude mcp add --transport http --scope user mnemonic "http://127.0.0.1:${MNEMONIC_MCP_PORT:-8001}/mcp" --header "Authorization: Bearer ${MNEMONIC_API_KEY}"

Registering the endpoint does not connect it to a running session. Claude Code loads MCP servers at startup, so start a new session afterwards.

In PowerShell, the URL and header expressions are "http://127.0.0.1:$env:MNEMONIC_MCP_PORT/mcp" and "Authorization: Bearer $env:MNEMONIC_API_KEY"; PowerShell has no :- default, so set the port variable explicitly there. Do not paste the real key into tracked project configuration. Configuration examples, including a Docker stdio alternative and OpenCode, live in examples/; they show the default ports and need the same substitution if yours differ. work.json is the canonical work body. Copyable workflows are duplicate-suggestion.json, discovered-work.json, human-gate-request.json, human-gate-resolution.json, and the irreversible merge-work.json request. Replace every placeholder and read both exact work contexts before using the merge example. The atomic completion examples are completion-with-evidence.json and completion-without-evidence.json, with a two-episode response in completion-evidence-history.json. Replace every provenance, version, UUID, result, and artifact placeholder with facts from the exact attempt; never copy example evidence as if it were observed.

The three skills ship as a Claude Code plugin. For a published server release, register its version-pinned marketplace and enable the matching plugin. Replace X.Y.Z with your server release; its compatibility table records the independent plugin version:

claude plugin marketplace add "https://github.com/RightBrain-Networks/mnemonic/releases/download/vX.Y.Z/marketplace.json"
claude plugin install mnemonic@mnemonic

To make it automatic for everyone who clones a consuming repository, commit this to that repository's .claude/settings.json instead:

{
  "extraKnownMarketplaces": {
    "mnemonic": { "source": { "source": "url", "url": "https://github.com/RightBrain-Networks/mnemonic/releases/download/vX.Y.Z/marketplace.json" } }
  },
  "enabledPlugins": { "mnemonic@mnemonic": true }
}

Contributors can register a local checkout with claude plugin marketplace add /path/to/mnemonic, or use { "source": "directory", "path": "/absolute/path/to/mnemonic" } in that settings file. That local catalog follows the checkout. Published catalogs pin both a release tag and its source commit.

Before upgrading the server, select its matching marketplace URL and plugin compatibility entry from the release. See release installation and verification for checksums and provenance.

Installing copies the plugin into ~/.claude/plugins/cache/ at its manifest version, so editing a skill in place does not change an installed copy. claude plugin marketplace update mnemonic refreshes the marketplace listing, not the installed files. After a published plugin version changes, run claude plugin marketplace update mnemonic, then claude plugin update mnemonic@mnemonic, and restart Claude Code.

Use a matching release of the application, worker, and compatible plugin. See GitHub Releases and the coordinated upgrade procedure before upgrading an existing database; older processes must not run against the new schema. Its repository-freshness helper requires Bash 3.2 or newer and Git 2.45 or newer in the explicitly selected local workspace. It provides:

• mnemonic-save searches for existing work, explicitly compares a stable

• mnemonic-search finds compact work-item leads within the chosen project,

• mnemonic-recall loads bounded current context, pages older checkpoints

Invoke /mnemonic:mnemonic-save, /mnemonic:mnemonic-search, or /mnemonic:mnemonic-recall, or ask Claude in natural language. The skills require the connected mnemonic MCP server. You can copy the selected project's ID from the dashboard, or use list_projects. Session IDs are opaque text (often UUIDs), not integers, and refer to the originating LLM conversation, not the MCP transport session.

See docs/agents.md for the workflow and client boundaries.

Connect Codex or OpenCode

Merge examples/codex.config.toml or examples/opencode.json into the client's configuration, substitute your MCP port, and export MNEMONIC_API_KEY in the environment that launches the client. Codex uses bearer_token_env_var; OpenCode uses {env:MNEMONIC_API_KEY} with oauth: false.

Install the three complete portable skill folders using scripts/export_agent_skills.py and the multi-client setup instructions. Connecting MCP does not install the skills. For Codex, also merge the AGENTS guidance into existing instructions. Restart the client and verify tool discovery and list_projects; an empty list is valid.

Operate and develop

docker compose ps
docker compose logs --tail=100 api mcp web worker rabbitmq
docker compose stop
docker compose up -d --wait

Use the same explicit -f overlays as at installation for these commands. Normal stop/restart preserves the database. Production stop/restart or recreation requires explicit operator authorization. Do not use docker compose down -v on your working stack: it removes the database, RabbitMQ, and application data volumes. Project backups are written as .json.bz2 archives under /backups// in the worker: the private backup named volume for new installs, or MNEMONIC_BACKUP_DIR for bind installs. The worker schedules them every 24 hours by default and retains seven successful archives per project. No archive is expected before a real project exists. Verify a backup in Settings → Project backups after creating your first project. Copy them off the machine and monitor available disk space; a local archive alone does not protect against disk loss. Artifact files, editable prompt files, and retained native transcripts require separate filesystem backups. Restore commands and security limits are in docs/operations.md.