setup-ai-memory

Files (1)

• SKILL.md

SKILL.md (first lines)

# Setup ai-memory

**Multi-tool (primary path):** run `~/Projects/cursor-kit/sync-all.sh` (subset via `TOOLS="claude cursor codex gemini"`). It installs/repairs the binary + LaunchAgent and wires every tool. Verify with `claude mcp list`, `codex mcp list`, `ai-memory doctor`. Cursor-specific steps below apply only to Cursor.

Opt-in **companion** for long-horizon project memory. Compose upstream
[ai-memory](https://github.com/akitaonrails/ai-memory) with cursor-kit — do not
fork, do not vendor their SKILL.md, do not replace kit episodic state.

Canonical kit root: `~/Projects/cursor-kit` (or this plugin repo). Human doc (PT):
`docs/tools/10-ai-memory.md`. Pasteable prompt: `docs/prompts/07-ai-memory-wire.md`.

## Ownership (do not blur)

| Layer | Authority |
|-------|-----------|
| Prefs / facts | `AGENTS.md` (continual-learning) |
| Architecture | `PROJECT.md` Decisions |
| Live task / continue | `.claude/state/checkpoint.json` |
| Tool failures | `.claude/state/failures.jsonl` |
| Long-horizon wiki / handoff / FTS | ai-memory (when enabled) |

Retrieval still starts with kit layers; only then ask ai-memory MCP for handoff/brief.

## Process

### 0. Consent

Confirm once: install/repair companion on this machine? (recommended for solo
macOS Cursor + optional Claude/Codex later). If declined, stop and point at the
PT doc.

### 1. Pré-check

| Check | Healthy | Action |
|-------|---------|--------|
| macOS + arch | Darwin arm64/x86_64 | Else: point upstream install docs; do not run kit script |
| Binary | `ai-memory` on PATH or `~/Applications/ai-memory/ai-memory` | Run kit installer |
| Server | `curl` `http://127.0.0.1:49374/mcp` → 405 (or 401 with auth) | Start LaunchAgent / `serve` |
| MCP | `~/.cursor/mcp.json` has ai-memory | `install-mcp --client cursor --apply` |
| Hooks | hooks.json has kit **and** ai-memory commands | `install-hooks --agent cursor --apply`; never wipe kit hooks |

### 2. Install / repair

Prefer kit script (idempotent):

```bash
# from cursor-kit root
./scripts/install-ai-memory.sh
```

Defaults: native release tarball → `~/Applications/ai-memory`, LaunchAgent,
loopback bind, zero-LLM OK, then upstream `install-mcp` / `install-hooks` for
**cursor**.

Overrides: `AI_MEMORY_HOME`, `AI_MEMORY_SKIP_LAUNCHD=1`, `AI_MEMORY_SKIP_WIRE=1`,
`AI_MEMORY_FORCE_DOWNLOAD=1`.

Do **not** download without user consent if they only asked for docs.

### 3. Preserve kit hooks

After wiring, if the user runs `./sync-hooks.sh`, it must be **merge-safe**
(kit scripts only; companions preserved). If an old overwrite wiped ai-memory
entries, re-run `ai-memory install-hooks --agent cursor --apply` via the real
binary path under `~/Applications/ai-memory/ai-memory` (not a broken symlink).

### 4. Verify

1. LaunchAgent running (or foreground `serve`)
2. Loopback `/mcp` returns 405
3. MCP lists ai-memory beside token-engine / codebase-memory
4. `hooks.json` still includes kit `*.py` hooks **and** ai-memory hook commands
5. Remind: Reload Cursor MCP / window
6. Optional: `memory_status` via MCP; do not dump secrets

### 5. Done report

```markdown
## ai-memory setup

- Consent: accepted | declined
- Binary: path | missing
- Server: up (code) | down
- MCP: wired | repaired | skipped
- Hooks: kit+companion | kit-only | needs re-wire
- Next: reload MCP; use checkpoint for continue; wiki for long-horizon recall
```

## Guardrails

- Composition: call upstream CLI; never paste their hook scripts into the plugin
- No second **episodic** store — checkpoint remains continue/retomar authority
- No secrets in wiki or kit memory files (`memory-security`)
- No absolute machine-specific paths in committed docs
- Docker path is secondary on macOS; kit default is native + LaunchAgent
- Depth 1 `/setup-project` does not require this companion

## Out of scope

- Homelab multi-user auth / TLS (point at upstream deploy docs)
- Making `ai-memory run` the Cursor launcher
- Dual-write AGENTS ↔ wiki
- Cloud Projects VM install (companion is desktop/loopback-first)

From Bossmann007/cursor-kit, MIT.

More from Bossmann007/cursor-kit