Memory Sync

---
name: memory-sync
description: Audits and updates local agent memory. Scans configured coding folders, registers or ignores new projects, writes PROJECTS.md, syncs your Agent injection. Use when the user says Bestandaufnahme, memory sync, neues Projekt, inventory, Projekte updaten, register project, or wants agents to know a new repo path.
---

# memory-sync

Local markdown memory. Not cloud.

## Paths

<!-- agents-memory-paths -->
User memory: `~/.agents/memory`. Project memory: `<repo>/.agents/memory`.
<!-- /agents-memory-paths -->

| File | What |
|------|------|
| `~/.agents/memory/USER.md` | Identity, talk style, stack, ALWAYS/NEVER |
| `~/.agents/memory/PROJECTS.md` | slug / path / role / stack / status |
| `~/.agents/memory/concepts/` | Ideas |
| `~/.agents/memory/entities/` | Named things |
| `~/.agents/memory/workflows/` | Procedures |
| `~/.agents/memory/projects/<slug>/` | Link to a real tree (not a second copy) |
| `~/.agents/memory/notes/<collection>/` | Personal notes. Guide: projects, interests, education, finance, family, preferences, programming, work, certifications, scratch — **not a closed set** |
| `<repo>/.agents/memory/staging/` | Inbox only (`captured.md`, `from-chats.md`). Distill, then empty. |
| `<repo>/.agents/memory/` | research (input); `plans/` `tasks/` `waves/` `roadmap/` `decisions/` as `001-topic.md`; `notes/proposed\|implemented\|rejected/<class>/` |
| `~/.agents/AGENTS.md` | Canonical always-on (USER + PROJECTS). `CLAUDE.md` is bound to it. |
| `~/.agents/memory/chats-index.md` | Chat title catalog |
| `~/.agents/memory/scan.json` | Roots, ignore list (includes `.agents`, `.cursor`), agent rule name |
| `~/.agents/rules/*.mdc` | Personal always-on rules (canonical). Sync binds them into `~/.cursor/rules/`. Example: `run-commands.mdc` |

MCP server `agents-memory`: see [`abi/MCP.md`](../../abi/MCP.md). CLI/injection: `python -m agents_memory --help-json`.

## When this skill fires

- User asks for Bestandaufnahme / inventory / memory sync / Projekte updaten
- User asks about cloud sync, VPS assistant memory, or multi-device status
- User (or you) created a **new folder** under a `scan.json` root
- A path in `PROJECTS.md` is wrong or missing
- After editing `USER.md` or `PROJECTS.md` by hand → always `python -m agents_memory sync`

## Cloud mirror sync

Cloud = source of truth; local files = working copy. All MCP tools run **locally**; push/pull syncs a mirror bundle — see [`abi/REMOTE.md`](../../abi/REMOTE.md).

| Step | Where | Command / MCP |
|------|-------|---------------|
| Connect | Workstation | `python -m agents_memory connect <URL> --token <TOKEN>` |
| Ingest catalog+extract | **Workstation** (chat graves local) | MCP `ingest_catalog` + `ingest_extract` or `ingest run` — auto-pushes |
| Distill staging | **Local** | MCP `get_staging_inbox` → `distill_batch` / `auto_distill` — auto-pushes. Noise pass after extract when inbox >= threshold |
| Inventory / register | **Local** | MCP `inventory_projects` / `register_project` — auto-pushes |
| Search / CRUD | **Local** (merged after pull) | MCP `search_memory`, `add_memory`, … |
| Repo facts | **Local repo** | MCP `add_memory(project=…)` → `<repo>/.agents/memory/` — mirrored to cloud |
| Status | Either | `python -m agents_memory remote status` |
| Disconnect | Workstation | `python -m agents_memory disconnect` (final pull) |
| Manual sync | Workstation | `remote push` / `remote pull` / `remote pull --replace` (exact snapshot; backup first) / `remote push --replace` or `remote bump-epoch` after a cleanup / `python -m agents_memory sync --push` (hand-edits). A stale epoch parks local edits in `staging/epoch-questions.md` (`get_staging_inbox`); it does not push them. |

After `connect`, IDE MCP entry is `agents_memory.remote.sync_mcp` (pull on start, push after writes).

## Inventory workflow

1. Run `python -m agents_memory inventory` (or MCP `inventory_projects`).
2. Show the user a tight list:
   - **unknown**: on disk, not in memory
   - **missing**: in memory, path gone
3. For each **unknown**, ask (or infer if obvious):
   - **add** → role + stack (one line each)
   - **ignore** → never list again (`ignore_project` / `--ignore SLUG`)
   - **skip** → leave for later
4. Register adds write `PROJECTS.md`, `projects/<slug>/README.md` (link), and `<repo>/.agents/memory/` **files** (`README.md`, `staging/captured.md`), then sync inject. No empty folders. No repo `.cursor/`.
5. For **missing**: confirm delete from `PROJECTS.md` or fix the path. Do not guess a new path.
6. Run `python -m agents_memory sync` if you edited markdown by hand.
7. Tell the user: your Agent picks up MCP + rules after reload if the server name changed.

## New project while coding (no full audit)

If you scaffold a repo under a scan root:

1. `register_project` immediately (slug, absolute path, role, stack).
2. Do not wait for the user to remember. If role is unclear, register as `unclassified` and ask one question.
3. Never leave a new repo off `PROJECTS.md`. The always-on map is useless if it is stale.

## Edit rules

- Durable identity → `~/.agents/memory/USER.md` then `python -m agents_memory sync`
- Idea → MCP `add_memory(kind="concept"|"entity", name="stem")`
- Procedure → `add_memory(kind="workflow", name="stem")`
- Project **link** → `add_memory(kind="project", name="slug")` writes `projects/<slug>/README.md` pointing at the real tree
- Ordered work → `kind="plans"|"tasks"|"waves"|"roadmap"` with `project=` → `001-topic.md`
- Decision / claimed contract → `kind="decision"|"adr"` → `decisions/001-title.md`
- In-flight design note → `kind="proposed"|"implemented"|"rejected"`, `collection=` class (`architecture` default). **implemented** and **decisions** = revise the file in place when shipped reality changes; **rejected** = frozen.
- Research (input) → `kind="research"` — revise topical file when input changes
- Project fact → `project="slug"` alone or `kind="fact"` → `<repo>/.agents/memory/facts.md` (direct fact, skips staging)
- Inbox / Raw Dump → `kind="staging"` → `staging/captured.md`. Distill, then delete the bullet.
- Personal note → `add_memory(kind="note", name="stem", collection="interests"|…)` or `project="slug"` for `notes/projects/<slug>/`
- Throw-away → `kind="scratch"`
- No `facts.md`. Path encodes the home.
- Chat titles → `python -m agents_memory ingest catalog`. Extract → `python -m agents_memory ingest extract` then distill. **Ingest always local**; mirror sync auto-pushes after ingest/distill/CRUD. See `abi/INGEST.md` + `abi/REMOTE.md`.
- `AGENTS.md` is the real file. `CLAUDE.md` is bound to it (symlink → hardlink → copy) **only when CLAUDE.md has no text outside the memory block**. Edit `AGENTS.md`. See `abi/PLATFORM.md` for Windows vs macOS/Linux.
- `python -m agents_memory sync` splices `<!-- agents-memory-sync -->` … `<!-- /agents-memory-sync -->` into existing `AGENTS.md`. It does not replace the file.
- Do not copy secrets, tokens, SSH keys, emails, phones, or `.env` values into memory
- Do not overwrite a repo root `AGENTS.md`. If you inject there, append the memory brackets only.

## Off / parked

Empty or spec-only folders stay in the table with `status: parked` so inventory does not nag. Ignore only if the folder should never be a project.