Skill

---
name: carryover
description: "Use when recalling, saving or curating carryover memory, wikis, playbooks or the Obsidian vault."
version: 1.0.0
license: MIT
metadata:
  hermes:
    tags: [memory, recall, knowledge, obsidian, wiki, playbooks, carryover]
    homepage: https://github.com/Cfvillarroel/carryover
---

# carryover

[carryover](https://github.com/Cfvillarroel/carryover) is a local, cross-tool memory layer:
one SQLite store (`~/.headroom/memory.db` with headroom, else `~/.carryover/memory.db`) shared by
Claude Code, Codex, Cursor and Hermes. It holds **memories** (facts + typed entities +
relationships, indexed by repo), per-repo **auto-wikis**, `!macro` **playbooks**, a cross-workspace
**inbox**, and materializes everything into an **Obsidian vault**.

Everything runs on this machine. No network, no telemetry.

## What is already automatic

Once `hermes/install-hermes.sh` has run, two shell hooks do this without being asked:

- **`pre_llm_call`** — on a session's first turn injects what carryover knows about the repo in
  `cwd` (its group) plus a few `general` facts; every turn it delivers pending workspace messages
  and expands any `!playbook` named in the prompt; after edits it raises the save-what-mattered prompt.
- **`post_tool_call`** — flags the session as "files changed" after `write_file` / `patch` / `terminal`.

So do **not** run a recall command just to see the repo's context at the start of a session — it is
already in your prompt. Reach for the commands below when you need *more* than that.

## Recall

| Need | Do |
|---|---|
| Anything beyond the injected bullets | `co-recall "<query>"` (this repo's group) · `co-recall --all "<query>"` |
| From an MCP client / another repo's knowledge | the `mcp_carryover_recall` tool (`repo` arg scopes it; omit for all repos) |
| Structural questions — what links to X, hub entities, notes mentioning X **and** Y | grep the vault, not the store: `~/Documents/carryover-vault/knowledge/*.md` (frontmatter `id`/`repo`/`entities`) and `entities/*.md` (`[[backlinks]]`) |

Recall is semantic when headroom is installed, keyword otherwise (`co-mem backend` says which).

## Saving

Prefer structured saves — each fact becomes its own searchable memory and the entities/relationships
build the graph:

```bash
mem-save --json '{"content":"1-line summary",
                  "facts":["atomic, self-contained facts"],
                  "entities":[{"entity":"X","type":"project|tech|person|concept"}],
                  "relationships":[{"source":"X","relationship":"uses","destination":"Y"}],
                  "category":"area","tags":["…"],"importance":0.7}'
mem-save "plain text"          # when structuring isn't worth it
```

Saves run in the background (embedding load) and are tagged with the current repo automatically.

- `co-forget "<query>"` — delete by keyword, with confirmation.
- `co-supersede <old-id> <new-id>` — hide a stale memory so the updated fact wins. Prefer this over
  deleting when the old fact was true at the time.
- Importance is 0..1; 0.7 is the default. Raise it for decisions and invariants, not for trivia.

**What deserves a memory:** decisions and their rationale, invariants, non-obvious conventions,
gotchas that cost time. Not: task progress, PR numbers, anything stale within a week.

## Wikis

Per-repo, generated by headless `claude -p`, incremental (existing pages are preserved).

```bash
cd /path/to/repo && co-wiki-enable   # enable + generate the first wiki (background)
co-wiki-gen                          # update on demand
WIKI_PUBLISH=1 co-wiki-gen           # also push to the GitHub wiki
```

## Obsidian vault

```bash
co-vault              # build/refresh → ~/Documents/carryover-vault (knowledge + entities + wikis)
co-vault insights     # grounded, self-verified cross-memory insights → INSIGHTS.md
co-vault merge        # LLM-group synonymous entities into a hand-editable map
co-vault clean        # rebuild derived config/hubs; keeps edits, never touches the store
```

Two-way: editing a note's first paragraph or raising its `importance` in Obsidian syncs back on the
next `co-vault`, so later recalls rank it higher. Facts, entities and relationships are derived and
read-only.

## Cross-workspace messaging

```bash
co-send <workspace|project|all> "<message>"   # leave a note
co-inbox [--peek|--all]                       # read (reading consumes; --peek doesn't)
co-connect <name> && co-say "<message>"       # persistent two-way link
co-team send|assign <team> [@role] "<msg>"    # roster on top of the same store
```

The `pre_llm_call` hook already delivers pending notes each turn — run `co-inbox` only to re-read
(`--all`) or to check without consuming (`--peek`).

## Playbooks

Markdown procedures in `~/.carryover/playbooks/`. Any `!name` in the user's prompt injects
`<name>.md` — the hook does this, you just follow the procedure. `co-playbooks` lists them.

## Health & maintenance

```bash
carryover doctor [--fix]   # health-check the whole setup
co-dash                    # local dashboard :8788 — browse/manage knowledge, wikis, playbooks
co-mem backend             # which store is active (headroom = semantic, builtin = keyword)
co-backup / co-restore     # move the store to another machine
```

## Pitfalls

- **Hooks and MCP servers are read at Hermes startup.** After `carryover update` or any change to
  `config.yaml`, restart Hermes — a reconfigured hook does not hot-reload.
- **The MCP server has no working directory**, so `mcp_carryover_recall` without a `repo` argument
  searches every repo. Pass `repo` to scope it.
- **`hermes config set` cannot write the hook list.** Use `hermes/configure-hermes.py`
  (install/uninstall/status) — it merges only carryover's entries and keeps a `.carryover.bak`.
- **Semantic vs keyword recall** depends on the interpreter the hooks run under. If recall feels
  literal, check `co-mem backend`: `builtin` means headroom's venv wasn't found at install time.
- Group related repos (front + back of one product) on one line of `~/.carryover/groups.conf` so
  they share recall.