{
  "markdown": "# memini\n\n[![npm version](https://img.shields.io/npm/v/memini)](https://www.npmjs.com/package/memini)\n[![CI](https://github.com/lumayapartners/memini/actions/workflows/ci.yml/badge.svg)](https://github.com/lumayapartners/memini/actions/workflows/ci.yml)\n[![memini MCP server](https://glama.ai/mcp/servers/lumayapartners/memini/badges/score.svg)](https://glama.ai/mcp/servers/lumayapartners/memini)\n\n**Never the same mistake twice.** Mistake-prevention guardrails and persistent project memory for AI coding agents.\n\nAI 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.\n\nNot a notebook the agent may choose to read. A guardrail it can't skip.\n\n![memini demo — an agent is stopped before repeating a recorded deploy mistake](docs/assets/demo.gif)\n\n## How it works\n\n1. **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.\n2. **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:\n   > `[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`.\n   - `warn` severity: the agent is warned once per session, then may proceed.\n   - `block` severity: the edit is always denied until a human archives the memory.\n3. **Session start injects a digest** of the most important memories (severity-first, token-budgeted).\n4. **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`.\n5. **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.\n\n## Quickstart (90 seconds)\n\n```bash\ncd your-repo\nnpx -y memini init       # creates .memini/ + installs Claude Code hooks\n\n# record your first guardrail\nnpx -y memini remember failed_attempt \\\n  \"Editing vercel.json broke the build\" \\\n  -b \"Tried changing buildCommand; deploy failed. Fix: move checkout server-side.\" \\\n  --file vercel.json --severity warn\n```\n\nThat's it. Next time any Claude Code session in this repo tries to edit `vercel.json`, it gets the warning first.\n\n**Cursor, Windsurf, and other MCP clients:**\n\n```bash\nclaude mcp add memini -- npx -y memini mcp   # Claude Code MCP\nnpx -y memini install-mcp --write cursor     # Cursor: MCP + rule + enforced preToolUse hook\nnpx -y memini install-copilot                # GitHub Copilot: enforced preToolUse hook (.github/hooks)\nnpx -y memini install-mcp                    # print generic MCP config\n```\n\n**Enforcement is a chain of gates, and memini covers several:**\n\n- **Before the edit** — the edit to a guardrailed file is blocked before it happens.\n  `block` → denied, `warn` → the user is prompted with the recorded history. Supported on:\n  - **Claude Code** — `pm init` installs it\n  - **Cursor** (1.7+) — `pm install-mcp --write cursor`\n  - **GitHub Copilot** — CLI, cloud coding agent, and VS Code agent mode (preview) — `pm install-copilot`\n- **Before the commit — every tool** — a git pre-commit guardrail blocks a commit that touches\n  a `block`-severity file, no matter which IDE or agent made the edit (Windsurf, Cline, a human…).\n  Installed by `pm init` (or `pm install-hooks --git`). Fails open; overridable with\n  `git commit --no-verify`.\n- **Advisory — any MCP client** — the `check_before_editing` / `recall_project_context` tools,\n  plus an always-applied Cursor rule steering the agent to use them.\n\n## Keeping memory useful over time\n\nA memory tool is only as good as what's in it, and it rots if left alone. memini keeps it healthy:\n\n- **Auto-capture** — a Claude Code session-end hook nudges the agent to record durable lessons\n  (a fix that worked, a fragile file, a failed approach) when a session actually changed files,\n  so you don't have to remember to `pm remember`. It stays silent on idle sessions.\n- **Usefulness tracking** — every time a guardrail actually fires, memini counts it. `pm stats`\n  shows which memories are pulling their weight and which have never fired.\n- **`pm review`** — flags near-duplicates, contradictory guardrails on the same file, and dormant\n  guardrails that have never fired long after creation. All local heuristics, no LLM — you decide\n  what to keep, merge, or archive.\n- **Git-aware staleness** — memories hash the files they reference; when the code changes, the\n  memory is flagged and stops firing until re-verified (`pm stale` / `pm verify`).\n\n## CLI\n\n| Command | What it does |\n|---|---|\n| `pm init` | Set up `.memini/`, gitignore, and hooks |\n| `pm remember <type> <title> [-b body] [--file f...] [--severity warn\\|block]` | Record a memory |\n| `pm recall [query] [--file f] [--digest]` | Search memories / preview the agent digest |\n| `pm check <path>` | Guardrail check (exit 1 if risks recorded) — usable in CI |\n| `pm list / show / archive / approve <id>` | Manage memories |\n| `pm stats` | What your memory is doing — guardrail fires, coverage, staleness |\n| `pm review` | Surface quality issues: duplicates, contradictions, dormant guardrails |\n| `pm stale` / `pm verify <id>` | Detect and re-verify outdated memories |\n| `pm mcp` | Run the MCP server (stdio) |\n| `pm doctor` | Diagnose setup |\n\nMemory types: `decision`, `failed_attempt`, `fragile_file`, `architecture`, `deployment`, `client_preference`, `session_summary`.\n\n## Scopes: sharing rules across repos\n\nSome lessons are project-specific; some apply to every repo on your machine that belongs to the same org or client. memini has three scopes:\n\n| Scope | Where it lives | Use it for |\n|---|---|---|\n| `project` (default) | `<repo>/.memini/` | this repo's failed fixes, fragile files, decisions |\n| `workspace` | `.memini/` in a parent folder of your repos | org/client conventions shared by every repo under that folder |\n| `user` | `~/.memini/` | personal rules that follow you everywhere |\n\n```bash\ncd ~/work/acme && pm init --workspace     # one-time: workspace store covering ~/work/acme/*\n\n# from inside any repo under ~/work/acme:\npm remember deployment \"DB connections must use org OAuth, never PATs\" \\\n  --file \"databricks.yml\" --severity warn --scope workspace\n\npm promote <id> --workspace               # lift a project lesson that turned out to be org-wide\n```\n\nEvery 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.\n\n## Design principles\n\n- **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.\n- **Human-readable, PR-able.** Every memory renders to markdown under `.memini/` that your team reviews like any other change.\n- **Git-linked evidence.** Memories record the branch, commit, and file hashes they were born from, so claims are verifiable and staleness is detectable.\n- **Local-first.** SQLite + markdown in your repo. No accounts, no cloud, no telemetry. Secrets are auto-redacted from memory bodies before they're stored.\n- **Cross-tool.** Core is a CLI + files; Claude Code hooks and MCP are thin adapters.\n\n## Security\n\nLocal-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](./SECURITY.md) for the full threat model — including the honest limitations (guardrails intercept edit tools, not arbitrary shell; `warn` is advisory, `block` is not).\n\n## Status\n\nEarly (v0.1). Team sync — shared memory across your whole team, with a review workflow — is on the roadmap. Feedback and issues welcome.\n\n## License\n\nMIT\n",
  "bytes": 8703,
  "sha": "b01f503065fc9ec83e7fb3161be0dab67720e7dc80f98c739f44af51c5f09bb5",
  "repo_slug": "lumayapartners/memini",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lumayapartners_memini_1e35d4be/readme"
}