{"id":51199320,"url":"https://github.com/mattrichmo/memory-magico","last_synced_at":"2026-06-27T23:30:52.534Z","repository":{"id":365613803,"uuid":"1272916901","full_name":"mattrichmo/memory-magico","owner":"mattrichmo","description":"Git-based CLI memory harness for AI agents: structured project memory, flexible wiki, CLI workflows, role-based agents, provenance, and reviewable history.","archived":false,"fork":false,"pushed_at":"2026-06-18T05:02:36.000Z","size":1335,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T06:23:28.634Z","etag":null,"topics":["agent-memory","agent-skills","agentic-workflow","ai-agents","cli","git","git-based-wiki","git-native","lmwiki","local-first","memory","project-management","sprint-planning"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattrichmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T03:41:33.000Z","updated_at":"2026-06-18T05:20:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mattrichmo/memory-magico","commit_stats":null,"previous_names":["mattrichmo/memory-magico"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mattrichmo/memory-magico","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattrichmo%2Fmemory-magico","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattrichmo%2Fmemory-magico/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattrichmo%2Fmemory-magico/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattrichmo%2Fmemory-magico/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattrichmo","download_url":"https://codeload.github.com/mattrichmo/memory-magico/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattrichmo%2Fmemory-magico/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34872279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agent-skills","agentic-workflow","ai-agents","cli","git","git-based-wiki","git-native","lmwiki","local-first","memory","project-management","sprint-planning"],"created_at":"2026-06-27T23:30:47.953Z","updated_at":"2026-06-27T23:30:52.525Z","avatar_url":"https://github.com/mattrichmo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Memory Magico project image](src/assets/mm-project-head.png)\n\n# Memory Magico\n\nA local-first, Markdown-first memory harness for projects where humans and coding agents work from the same context. It gives agents a controlled path to ingest notes, reconcile them, maintain canonical project knowledge, plan and track work, log verification evidence, and pull focused context without relying on chat history.\n\nCreation should be cheap. Promotion should be deliberate. Verification should be expensive.\n\nThe `memory/` directory is the durable source of truth: knowledge, work items, raw intake, generated indexes, and agent role instructions. The CLI is the interface agents use to search, resolve, read, mutate, and verify that memory.\n\nThe basic flow:\n\n```text\ncapture cheaply -\u003e reconcile deliberately -\u003e promote to canonical memory -\u003e execute with evidence -\u003e verify before closure\n```\n\nAgent workflows tend to fail in predictable ways: context gets trapped in chats and screenshots, agents duplicate work because they can't tell what already exists, \"done\" gets declared without tests or evidence, raw notes get rewritten before anyone decides what they mean, and generated context drifts from canonical truth. MemoryMagico's structure — separate raw intake, canonical wiki pages, structured work records, generated indexes, and agent instructions — is aimed at those specific failure modes.\n\n---\n\n## Git as the memory log\n\nProject memory lives as plain files in the repo, not in a database or hidden agent state. That means every memory change is diffable, reviewable as a PR, revertible, branchable, and blameable — you can see when a claim, task, or decision entered the project, and roll it back if it's wrong.\n\n```bash\ngit status --short\nmm lint --json\nmm index rebuild\ngit diff -- memory/\ngit add memory/\ngit commit -m \"memory: record hardening audit findings\"\n```\n\nFor agent-heavy work this matters more, not less. Agents can write useful memory, but only if a human can inspect the diff, reject a bad change, or require evidence before merging. Rule of thumb: no memory mutation is trusted until it shows up in `git diff` and passes the standard checks.\n\n---\n\n## Core concepts\n\n| Concept | Purpose |\n|---|---|\n| Raw intake | Immutable source material: notes, files, screenshots, terminal output, audit findings, exports, pasted content. |\n| Wiki pages | Canonical Markdown/YAML knowledge — the pages agents should trust first. |\n| Work records | Initiatives, sprints, phases, tasks, issues, discoveries, comments, containers. |\n| Claims | Explicit assertions with confidence and source references; contradictions can be recorded. |\n| Relationships | Typed graph edges between issues, tasks, wiki pages, raw items, files, commits, and other entities. |\n| Generated indexes | Search, page, chunk, and dashboard artifacts derived from canonical memory — rebuildable, disposable. |\n| Agent roles | Source-controlled instructions installed into Claude Code or Codex-style agent surfaces. |\n| Trace logs | Optional append-only records of observed `mm` command activity for debugging agent workflows and inferred local sessions. |\n| Git history | The audit trail for every memory mutation, including agent edits, decisions, evidence, and rollbacks. |\n\nThe agent-facing rules are short: raw sources are immutable, wiki pages are canonical, generated indexes are disposable, agents resolve before they mutate, and verification evidence is required before anything is marked done.\n\nSearch uses a compact local store instead of one large JSON runtime index: `memory/generated/page-index.jsonl` and `memory/generated/chunks.jsonl` stay inspectable, while runtime postings and chunk metadata live under `memory/.mm/search/`. `memory/generated/search-index.json` is only a small backend pointer/manifest, not the operational search database.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TD\n  A[Raw intake] --\u003e B[Reconciliation]\n  B --\u003e C[Canonical wiki]\n  B --\u003e D[Structured work records]\n  C --\u003e E[Generated search index]\n  D --\u003e E\n  C --\u003e F[Dashboard snapshot]\n  D --\u003e F\n  E --\u003e G[\"resolve / search / context\"]\n  G --\u003e J[Agents and humans]\n  H[Agent roles] --\u003e I[Claude / Codex surfaces]\n  I --\u003e J\n  J --\u003e K[CLI mutations]\n  K --\u003e C\n  K --\u003e D\n  C --\u003e L[Git history]\n  D --\u003e L\n  L --\u003e M[diff / review / rollback]\n```\n\n```text\nmemory/            durable source of truth — wiki, work records, raw intake, agent roles\nsrc/, bin/         the mm CLI\nschemas/           JSON schema guardrails\ntemplates/         bundled default agent role definitions\n```\n\nFull repository layout, path resolution (`toolRoot`/`repoRoot`/`memoryRoot`), and dev setup live in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n### Optional trace logging\n\nMemoryMagico can trace observable CLI activity without depending on a Codex or Claude chat session identifier:\n\n```bash\nmm trace on --verbose\nmm trace mark \"security audit cleanup\"\nmm trace sessions\nmm trace show trace_...\nmm trace off\n```\n\nThe log lives under `memory/.mm/trace/events/*.jsonl`. Sessions are inferred from workspace, cwd, host, user, and idle timeout; upstream agent labels can be attached with `mm trace context set --agent codex --label \"...\"`. Trace data is evidence for debugging and later promotion, not canonical project truth by itself.\n\n---\n\n## Installation\n\n### Prerequisites\n\nNode.js 18 or newer. A Git repo is strongly recommended — Git is the audit log, review surface, and rollback mechanism for memory changes.\n\n### Local install\n\n```bash\nnpm link\nmm init\nmm doctor\nmm index rebuild\n```\n\n`mm init` is interactive when run from a terminal: it asks which repo should receive `.memorymagico.json`, where the memory folder should live, whether that memory folder should be a separate git repo/folder or live inside the selected repo, where generated agent files should be installed, and which agent integration to install. This keeps the npm package code outside the project while binding the local `mm` command to one explicit memory workspace.\n\n```bash\nmm init\nmm init --yes --project-root ~/projects/app --memory-root ~/projects/memory --separate-git\nmm init --yes --project-root ~/projects/app --memory-root ~/projects/memory --install-root ~/projects\nmm init --yes --project-root ~/projects/app --in-repo-memory --skip-agent-install\n```\n\nRun non-interactively (e.g. from CI or a script) and `mm init` skips the wizard. Use `--project-root` to choose where the project pointer is written, `--memory-root` to choose the actual memory workspace, and `--install-root` when `.agents/` or `.claude/` should live in a top-level folder beside both the project repo and `memory/`. After setup, `mm` resolves from the nearest pointer and validates its `workspaceId` against `memory/.mm/manifest.json`.\n\n`package.json` needs to declare the CLI entrypoint before `npm link` will work:\n\n```json\n{\n  \"type\": \"module\",\n  \"bin\": {\n    \"mm\": \"./bin/mm.mjs\",\n    \"memorymagico\": \"./bin/mm.mjs\"\n  }\n}\n```\n\n### Direct source usage\n\n```bash\nnode bin/mm.mjs init\nnode bin/mm.mjs doctor\nnode bin/mm.mjs index rebuild\n```\n\nOr alias it:\n\n```bash\nalias mm=\"node $(pwd)/bin/mm.mjs\"\n```\n\n---\n\n## Quick start\n\n```bash\nmm init\nmm doctor\nmm index rebuild\n```\n\nCreate a canonical wiki page:\n\n```bash\nmm wiki create \"Delivery Check\" --kind concept\nmm search \"delivery check\"\nmm resolve \"delivery check\"\nmm context \"delivery check\" --deep\n```\n\nAdd a raw note and inspect it:\n\n```bash\nmm raw add --text \"Need to document how sprint launch agents should verify task evidence.\"\nmm raw list\nmm raw show raw_...\n```\n\nPromote or reconcile it:\n\n```bash\nmm ingest raw_...\nmm index rebuild\nmm raw process raw_... wiki_page wiki_delivery_check memory/wiki/concepts/delivery-check.md\n```\n\nHealth checks:\n\n```bash\nmm doctor\nmm lint\nmm index status\n```\n\n---\n\n## CLI overview\n\n```bash\nmm \u003ccommand\u003e [subcommand] [...args]\n```\n\n```bash\nmm help\nmm help search\nmm commands\nmm commands --json\nmm info\n```\n\nMost read commands support `--json`; agents should use it when parsing results programmatically.\n\n---\n\n## Safety model\n\nRaw intake is immutable: source material is captured before interpretation and isn't rewritten in place. Promotion is deliberate: raw items get reconciled against existing records and checked for duplicates or staleness before being promoted. Reads are bounded: agents use `mm read` instead of unbounded file reads. Output is machine-readable where it matters, via `--json`. Writes are lock-protected and atomic to avoid partial artifacts. Tasks and issues require real verification evidence before they can be closed. The dashboard binds to `127.0.0.1` by default. Generated artifacts (search index, dashboard data) are disposable and get rebuilt from canonical memory, not hand-edited. And every meaningful mutation should be visible in `git diff -- memory/` before it's trusted or merged — for large reconciliations, sprint launches, or refactors, do that work on a dedicated branch or worktree.\n\n---\n\n## Learn more\n\n| Doc | Covers |\n|---|---|\n| [CLI.md](CLI.md) | Full command reference, all flags, status/lifecycle values, troubleshooting. |\n| [docs/workflows.md](docs/workflows.md) | End-to-end cookbook: raw capture, reconciliation, sprints, issue verification gates. |\n| [docs/agent-system.md](docs/agent-system.md) | Agent role definitions, installation, rules, and the execution checklist. |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Full repository layout, dev setup, and testing. |\n| [DESIGN_NOTES.md](DESIGN_NOTES.md) | The governing rule and canonical-relationship conventions. |\n\n---\n\n## Roadmap\n\n- `mm status` — one-screen workspace health summary.\n- `mm safe` — `doctor + lint + index status + graph validation` in one command.\n- `mm audit` — hardening probes and command contract checks.\n- `mm snapshot`, `mm restore`, `mm rollback` — safer agentic mutation.\n- Stricter JSONL parsing in lint paths.\n- Uniform path containment checks at every command boundary.\n- Prompt-injection rules in every generated agent surface.\n- Promote useful trace sessions into raw/work evidence.\n- Optional SQLite backend for high-concurrency agent runs.\n- Shell completions generated from the command registry.\n\n---\n\n## License\n\nTBD.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattrichmo%2Fmemory-magico","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattrichmo%2Fmemory-magico","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattrichmo%2Fmemory-magico/lists"}