MCP 服务器

memini

Local-first project memory for AI coding agents. Records failed attempts, fragile files, and decisions per repo, and warns the agent via hooks before it repeats a recorded mistake.

README

memini

Never the same mistake twice. Mistake-prevention guardrails and persistent project memory for AI coding agents.

AI coding agents are stateless: every session starts with amnesia. The agent that broke your build editing vercel.json on Monday will happily try the exact same edit on Thursday. memini gives each repo a persistent memory of failed attempts, fragile files, decisions, and deployment rules — and force-feeds the relevant warning to the agent at the moment it's about to repeat history.

Not a notebook the agent may choose to read. A guardrail it can't skip.

memini demo — an agent is stopped before repeating a recorded deploy mistake

How it works

Memories live in your repo — a .memini/ folder with a local SQLite index and human-readable, PR-reviewable markdown views. Local-first: nothing leaves your machine.
Hooks enforce guardrails — when the agent tries to edit a file with recorded risks, the edit is intercepted before it happens and the recorded lesson is injected:

[WARNING] Editing vercel.json broke the build (recorded 2026-07-03) — Tried changing buildCommand; deploy failed. Actual fix: move checkout server-side and set VITE_STRIPE_USE_SERVER=true.
- warn severity: the agent is warned once per session, then may proceed.
- block severity: the edit is always denied until a human archives the memory.
Session start injects a digest of the most important memories (severity-first, token-budgeted).
MCP tools let the agent record what it learns: remember_failed_attempt, remember_fragile_file, remember_decision, end_session_summary, plus recall_project_context and check_before_editing.
Git-aware staleness — memories hash the files they reference; pm stale flags memories whose evidence has changed, and stale memories stop firing guardrails until re-verified.

Quickstart (90 seconds)

cd your-repo
npx -y memini init       # creates .memini/ + installs Claude Code hooks

# record your first guardrail
npx -y memini remember failed_attempt \
  "Editing vercel.json broke the build" \
  -b "Tried changing buildCommand; deploy failed. Fix: move checkout server-side." \
  --file vercel.json --severity warn

That's it. Next time any Claude Code session in this repo tries to edit vercel.json, it gets the warning first.

Cursor, Windsurf, and other MCP clients:

claude mcp add memini -- npx -y memini mcp   # Claude Code MCP
npx -y memini install-mcp --write cursor     # Cursor: MCP + rule + enforced preToolUse hook
npx -y memini install-copilot                # GitHub Copilot: enforced preToolUse hook (.github/hooks)
npx -y memini install-mcp                    # print generic MCP config

Enforcement is a chain of gates, and memini covers several:

Before the edit — the edit to a guardrailed file is blocked before it happens. block → denied, warn → the user is prompted with the recorded history. Supported on:
- Claude Code — pm init installs it
- Cursor (1.7+) — pm install-mcp --write cursor
- GitHub Copilot — CLI, cloud coding agent, and VS Code agent mode (preview) — pm install-copilot
Before the commit — every tool — a git pre-commit guardrail blocks a commit that touches a block-severity file, no matter which IDE or agent made the edit (Windsurf, Cline, a human…). Installed by pm init (or pm install-hooks --git). Fails open; overridable with git commit --no-verify.
Advisory — any MCP client — the check_before_editing / recall_project_context tools, plus an always-applied Cursor rule steering the agent to use them.

CLI

Command	What it does
`pm init`	Set up `.memini/`, gitignore, and hooks
`pm remember <type> <title> [-b body] [--file f...] [--severity warn\|block]`	Record a memory
`pm recall [query] [--file f] [--digest]`	Search memories / preview the agent digest
`pm check <path>`	Guardrail check (exit 1 if risks recorded) — usable in CI
`pm list / show / archive / approve <id>`	Manage memories
`pm stale` / `pm verify <id>`	Detect and re-verify outdated memories
`pm mcp`	Run the MCP server (stdio)
`pm doctor`	Diagnose setup

Memory types: decision, failed_attempt, fragile_file, architecture, deployment, client_preference, session_summary.

Scopes: sharing rules across repos

Some lessons are project-specific; some apply to every repo on your machine that belongs to the same org or client. memini has three scopes:

Scope	Where it lives	Use it for
`project` (default)	`<repo>/.memini/`	this repo's failed fixes, fragile files, decisions
`workspace`	`.memini/` in a parent folder of your repos	org/client conventions shared by every repo under that folder
`user`	`~/.memini/`	personal rules that follow you everywhere

cd ~/work/acme && pm init --workspace     # one-time: workspace store covering ~/work/acme/*

# from inside any repo under ~/work/acme:
pm remember deployment "DB connections must use org OAuth, never PATs" \
  --file "databricks.yml" --severity warn --scope workspace

pm promote <id> --workspace               # lift a project lesson that turned out to be org-wide

Every repo under the workspace folder — including ones you create later — gets those guardrails automatically. Resolution walks up the directory tree, like .gitconfig or ESLint configs. Workspace/user file guardrails match by glob (vercel.json matches any repo's vercel.json; config/**/*.yml works too), and wider-scope memories only fire when human-verified — agents can propose memories to project scope only, so a prompt-injected agent can't plant rules that spread across repos. pm doctor shows which scopes are active.

Design principles

Enforced, not advisory. MCP memory tools are optional for the agent; hooks are not. The guardrail path works even if the agent never thinks to check its memory.
Human-readable, PR-able. Every memory renders to markdown under .memini/ that your team reviews like any other change.
Git-linked evidence. Memories record the branch, commit, and file hashes they were born from, so claims are verifiable and staleness is detectable.
Local-first. SQLite + markdown in your repo. No accounts, no cloud, no telemetry. Secrets are auto-redacted from memory bodies before they're stored.
Cross-tool. Core is a CLI + files; Claude Code hooks and MCP are thin adapters.

Security

Local-first by design: no server, no account, no telemetry. Secrets are auto-redacted before storage, file references are contained to the repo, and injected memory text is size-capped and framed as data. See SECURITY.md for the full threat model — including the honest limitations (guardrails intercept edit tools, not arbitrary shell; warn is advisory, block is not).