mnemonn 1.3.4

Persistent project memory and a scoped knowledge graph for AI coding agents.

AI coding sessions lose the thread. Every new session re-asks for the branch goal, the plan, the constraints, the decision history, the half-finished task. Mnemon fixes this with a small, local-first memory layer: the agent reads a context block at session start and writes back what it learned, so the next session starts already oriented.

There is no hosted service and no vector database. Mnemon runs as an MCP server, stores everything in one SQLite file, and scopes memory by project and branch — the way software work actually happens.

Get started

Install the CLI, initialize your repository, and connect the MCP server.

Mac / Linux

curl -fsSL https://raw.githubusercontent.com/paulushcgcj/mnemon/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/paulushcgcj/mnemon/main/install.ps1 | iex

Via uv (all platforms)

uv tool install mnemonn

macOS note: if you see a security warning on first run, clear the quarantine flag once: xattr -d com.apple.quarantine /usr/local/bin/mnemon

One-off usage — run without installing:

uvx mnemonn read --help

From source (development):

git clone https://github.com/paulushcgcj/mnemon.git
cd mnemon
uv sync
uv tool install -e .

Connect your agent

Configure your MCP client to run Mnemon over stdio:

{
  "command": "mnemon",
  "args": ["serve"]
}

Initialize a repository

cd /path/to/your/repo
mnemon init

This detects the project id from git remote get-url origin and generates .github/copilot-instructions.md, which tells the agent to call Mnemon at session start and session end. Use --force to overwrite an existing file.

Your first session

1. Start — the agent calls memory_read(project_id, branch) and receives project context, branch focus, decisions, tasks, graph entities, and recent history.
2. Work — the agent updates task status, records decisions, and stores components and relations in the knowledge graph as they come up.
3. Close — the agent calls memory_summarize(...) with the session summary, current focus, and next steps.

The next session starts with all of it already available.

How it works

Mnemon keeps two complementary memory layers behind one MCP server.

Session memory

Answers "where are we right now?" — per project and per branch:

• project-wide context: stack, conventions, architecture notes
• branch-specific focus and next steps
• decisions, global or branch-scoped
• tasks with todo, in-progress, blocked, or done status
• recent session summaries and commit entries logged through memory_log_commit

Knowledge graph

Answers "what do we know about the important things here?":

• entities — components, concepts, files, people, systems, or custom types
• observations — factual notes attached to entities
• relations — typed connections such as calls, implements, depends_on, owns
• importance scores from 0.0 to 1.0

High-importance entities are included automatically in the session-start context, so architectural knowledge becomes working memory without a separate search step.

A session in practice

memory_read(project_id="owner/repo", branch="feature/imports")

Returns the full context block. During the session:

memory_task_update(task_id="a1b2c3d4", status="in-progress")

graph_entity_upsert(
  project_id="owner/repo",
  name="ImportService",
  entity_type="component",
  observations=["owns CSV validation"],
  importance=0.7
)

At the end:

memory_summarize(
  project_id="owner/repo",
  branch="feature/imports",
  summary="Implemented CSV validation path and added error handling.",
  current_focus="Finishing import validation edge cases.",
  next_steps="Add tests for malformed rows and empty files."
)

Tools & commands

MCP tools — session

MCP tools — graph

CLI

Every command accepts --format text|json and --out, and mnemon --version prints the installed version. Commands also perform a cached daily update check: a notice goes to stderr when a newer release exists, network failures are ignored, and MNEMON_NO_UPDATE_CHECK=1 disables it.

Storage & data model

Everything lives in one inspectable SQLite file:

~/.agent-memory/mnemon.db

Nine tables: projects, project_state, branch_state, decisions, tasks, session_log, entities, observations, relations.

The project id is inferred from the git remote, so each repository gets a stable namespace and each branch keeps its own focus:

git@github.com:owner/repo.git  ─┐
https://github.com/owner/repo.git ─┴─▶  owner/repo

Current state is overwritten; history is appended. Session logs, decisions, and observations accumulate while branch focus and task statuses stay current.

Development

Mnemon is a Python 3.12+ package managed with uv:

uv sync                  # install dependencies
uv run mnemon --help     # run the CLI locally
uv run mnemon serve      # start the MCP server
uv run pytest            # run the test suite
uv run mypy src          # strict type checking
uv run ruff check .      # lint

The package entry point lives in pyproject.toml:

[project.scripts]
mnemon = "mnemon.cli:cli"

Design principles

• Continuity over retrieval tricks. Mnemon focuses on what an agent needs to resume work, not on building a general-purpose RAG stack.
• Project and branch scope by default. Memory follows the way software work actually happens.
• Append history, overwrite state. Logs and observations accumulate; current focus stays current.
• Local and inspectable. Memory is SQLite, and the CLI reads the same data the server does.
• Small surface area. Easy to install, understand, and remove.

Status & roadmap

Mnemon is early software and usable today: install it, initialize a repository, connect an MCP client, and let the agent keep project memory as work progresses. See CHANGELOG.md for release history — v1.2.0 ships the opt-in PyPI update check and removes the old git-hook setup in favor of MCP-only commit logging.

Next up, in rough order: export/import for portability, richer graph inspection, and client-specific setup guides.

License

Distributed under the MIT License. See LICENSE for details.