Metadata-Version: 2.4
Name: memory-architect
Version: 0.2.2
Summary: Install the Memory Architect skills into any AI coding host — Claude Code, Cursor, Windsurf/Devin, Antigravity, Codex, Copilot, Cline, Gemini CLI.
Project-URL: Homepage, https://github.com/RohanRaoCs/memory-architect
Author-email: rroha <rrohanpqr@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents-md,ai,claude-code,cursor,memory,rag,skills
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<h1 align="center">🧠 Memory Architect</h1>

<p align="center">
  <a href="https://pypi.org/project/memory-architect/"><img src="https://img.shields.io/pypi/v/memory-architect" alt="PyPI"/></a>
  <a href="https://pypi.org/project/memory-architect/"><img src="https://img.shields.io/pypi/pyversions/memory-architect" alt="Python"/></a>
  <a href="https://github.com/RohanRaoCs/memory-architect/actions/workflows/publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/RohanRaoCs/memory-architect/publish.yml?label=publish" alt="CI"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"/></a>
</p>

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):

```bash
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](#install).

---

## See it in action

```text
$ 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:

```text
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:

```markdown
<!-- 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:**

```bash
# 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):**

```bash
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](LICENSE)
