memory-architect 0.2.2

Install the Memory Architect skills into any AI coding host — Claude Code, Cursor, Windsurf/Devin, Antigravity, Codex, Copilot, Cline, Gemini CLI.

🧠 Memory Architect

Type /memory-design in your AI coding assistant and it reads your codebase, researches the current AI-memory landscape live (Mem0, Zep, Letta, pgvector, Pinecone, Qdrant…), and writes a memory architecture doc tailored to your app — then /memory-ship builds it.

• Your assistant does the thinking. This package installs skills — precise markdown workflows — into whatever AI editor you already pay for. No API keys, no separate billing, no LLM calls from this tool. Zero runtime dependencies.
• Researched, not recalled. The design phase forces live web research: current GitHub health, real pricing pages, benchmarks. Stacks picked from training data go stale; these don't. A host that can't search must say so and mark claims unverified.
• Leaves no fingerprints. Every file it touches is manifest-tracked with sha256. Files you own (AGENTS.md etc.) get a fenced block + automatic backup. uninstall restores them byte-for-byte.

Get started (30 seconds):

uv tool install memory-architect        # install the CLI (or: pip install memory-architect)
memory-architect install --project      # register the skills with your AI editor(s)

Then, in your AI assistant:

/memory-design

Works in Claude Code, Cursor, Windsurf/Devin, Google Antigravity, Codex, Amp, Zed, Jules, OpenCode, Aider, Warp, JetBrains Junie, GitHub Copilot, Cline, Gemini CLI, and anything else that reads AGENTS.md — pick your platform.

---

See it in action

$ memory-architect install --project
Scope: project (~/support-bot)
Hosts: cursor, agents-md

  [create ] cursor      .cursor/skills/memory-design/SKILL.md   (+3 more skills)
  [update ] agents-md   AGENTS.md

This edits files you own (a backup is written first). Proceed? [y/N] y

Installed Memory Architect 0.2.1. Type /memory-design to start.

Then /memory-design runs a six-phase flow inside your assistant and ends with an approval gate like this before writing anything:

Proposed memory stack for support-bot

| Axis             | Choice                    | One-line rationale                     |
| ---------------- | ------------------------- | -------------------------------------- |
| Memory framework | Mem0 OSS v2.x             | per-user extraction, fits Node runtime |
| Vector database  | pgvector (your Postgres)  | reuse existing infra, $0 at your scale |
| Embedding model  | text-embedding-3-small    | best cost/recall for English support   |
| Graph layer      | Not needed                | no entity-relationship queries in app  |
| Memory storage   | Existing Postgres         | one database to operate                |

Considered and rejected: Zep — cloud-first pricing at your scale; Letta — heavier
agent runtime than the app needs; Pinecone — new infra where pgvector suffices…

Assumptions made: 1. English-only (no i18n config found) …
Shall I proceed with the full architecture document?

Approve → it writes memory-design/architecture.md: exact packages, env vars, schema, file:line wiring points, config knobs, cost projection.

---

The four workflows

Command	What it does	When
/memory-design	Reads your code → one round of multiple-choice questions → live research → approval gate → writes memory-design/architecture.md	First, or when memory needs a rethink
/memory-ship	Implements the architecture doc in your codebase — schema, read/write paths, tests — with checkpoints; refuses to declare done until checks pass	After design is approved
/memory-audit	Re-researches the landscape, diffs against your doc, verdicts HOLD / MINOR UPDATE / REDESIGN	Every 2–3 months
/memory-compare	Head-to-head of named frameworks for your use case, researched live	When evaluating alternatives

---

How it works

Two layers, one source of truth:

your-project/
├── .memory-architect/
│   ├── skills/*.md          ← full skill text, vendored once (4 files)
│   └── manifest.json        ← every file written, sha256-tracked
├── .claude/skills/…         ← native skill   (Claude Code)
├── .cursor/skills/…         ← native skill   (Cursor)
├── AGENTS.md                ← fenced pointer (Codex, Amp, Zed, Jules, …)
├── .agents/rules/…          ← pointer        (Antigravity)
├── .devin/rules/… + .windsurf/rules/…  ← pointer (Windsurf/Devin, under its 6k char cap)
├── .clinerules/…            ← pointer        (Cline)
├── .github/copilot-instructions.md     ← fenced pointer (Copilot)
└── GEMINI.md                ← fenced pointer (Gemini CLI)

Editors with native skill loading get real skills. Everything else gets a ~1.5 KB pointer stub — full workflow fidelity without stuffing 40k tokens into an always-on rules file. Fenced blocks in files you own look like:

<!-- BEGIN memory-architect v0.2.1 -->
…pointer stub…
<!-- END memory-architect -->

Install replaces only between markers. Uninstall removes the block and returns your file to its original bytes.

---

Install

Step 1 — install the package:

# Recommended (isolated env; if 'memory-architect' isn't found after, run: uv tool update-shell):
uv tool install memory-architect

# Alternatives:
pipx install memory-architect
pip install memory-architect     # may need PATH setup

# Or skip installing entirely — one-shot run:
uvx memory-architect install --project

Step 2 — register the skills with your AI editor(s):

memory-architect install --project    # this repo (committable — teammates get it via clone)
memory-architect install              # global: every project on this machine

install auto-detects the editors your project uses, prints the exact file plan, and asks before touching any file you own. Add --dry-run to preview without writing anything.

Or target one platform directly:

Platform	Command
Claude Code	memory-architect claude install
Cursor	memory-architect cursor install
Codex	memory-architect codex install
Google Antigravity	memory-architect antigravity install
Windsurf	memory-architect windsurf install
Devin	memory-architect devin install
Amp	memory-architect amp install
Zed	memory-architect zed install
Jules	memory-architect jules install
OpenCode	memory-architect opencode install
Aider	memory-architect aider install
Warp	memory-architect warp install
JetBrains Junie	memory-architect junie install
GitHub Copilot	memory-architect copilot install
Cline	memory-architect cline install
Gemini CLI	memory-architect gemini install
Agent Skills (cross-framework)	memory-architect agents install
Anything else	memory-architect generic install (prints a block to paste into any rules file)

Add --project to any of these to scope it to the current repo. Claude Code users can alternatively install via the plugin marketplace — this repo doubles as a Claude Code plugin (.claude-plugin/).

---

All commands

Command	What it does
memory-architect install [--project] [--host H] [--dry-run] [--force]	Wire the skills into detected or named editors
memory-architect uninstall [--project] [--host H]	Remove everything, restore your files byte-for-byte; works even if the manifest is lost
memory-architect status [--project]	What's installed, where, and whether any file drifted from its recorded sha
memory-architect doctor [--project]	Health check: payload present, managed files intact, Windsurf 6k/12k char budgets respected
memory-architect list	The four skills, nine host adapters, and what's detected on this machine
memory-architect hook install	Git post-commit nudge when architecture.md turns 90 days old

Safety guarantees

• Never overwrites blind. A file you've hand-edited is skipped with a warning (--force to override — and even then a .memory-architect.bak backup is written first).
• Never writes outside the install root. Every path is validated; a tampered manifest can't make uninstall delete arbitrary files.
• Dry-run means dry. --dry-run writes nothing, including no manifest.
• Uninstall is honest. Files it can't verify as its own are left in place and reported, never guessed at.

---

Troubleshooting

Symptom	Fix
Typing /memory-design does nothing	Your editor's / menu swallowed it. Type bare memory-design, or just ask "design a memory system for this app".
memory-architect not found after install	uv tool update-shell, then reopen the terminal.
"No supported host detected"	Fresh project with no editor folders yet — target explicitly: --host claude-code, --host agents-md, etc.
Skills not picked up in the editor	Rules load at session start — reload the window / start a new chat after installing.
Assistant answers about memory from stale knowledge	The skill mandates live research; if the host can't search the web it must say so. Prefer running design in an editor with web access.

---

FAQ

Does this call any LLM or phone home? No. It copies markdown into the right places. Your editor's own agent does all reasoning, on your existing plan.

What gets committed? With --project: the pointer files and .memory-architect/ — teammates clone and the skills are already wired. (Add .memory-architect/ to .gitignore if you'd rather they install themselves.)

Claude Code plugin vs pip install? Same skills. The plugin path is Claude-only; pip works everywhere including Claude.

Python version? ≥3.9, stdlib only.

---

License

MIT