# Horon Remote Memory Manual

This Horon instance stores your persistent long-term memory as named **concepts** (with `when_to_read` triggers, `content`, aliases, and tags).

## HTTP Calling Convention
- Endpoint: `POST /v1/cli`
- Headers: `X-API-Key: <your-key>` (or `Authorization: Bearer <your-key>`), `Content-Type: application/json`
- Body: `{"args": ["<command>", ...], "session_id": "<optional>"}`
- Batch body: `{"args": ["batch", "--all"], "batch_text": "<one command per line>"}`
- Response JSON: `{"ok": true|false, "output": "...", "error": "..."}`
  Note: `--content-file`, `--append-file`, `--old-file`, `--new-file`, `--file`, and `--out` are disabled remotely; always pass text inline.

## Core Commands
- `login [--recent N]` — Session start: loads `boot` concepts, recent mutations, and this manual.
- `search_semantic "<intent>" [--limit 10]` — Vector search over `when_to_read` triggers.
- `search_keyword "<text>" [--tag "A & B"] [--limit 50]` — Substring search across names, aliases, `when_to_read`, and content.
- `read_concept <name|alias|id> [...]` — Read full concept content, tags, and related suggestions.
- `list_concepts [--tag "A | B"]` — List concept names and `when_to_read` summaries.
- `recent [N]` — Show the N most recently mutated concepts.
- `create_concept "<name>" --when-to-read "<trigger>" --content "<markdown>"` — Create a new concept.
- `update <node> content --append "<text>"` — Append text to a concept's content.
- `update <node> content --old "<old>" --new "<new>"` — Patch content (`...` inside `--old` matches any span between two anchors).
- `set <node> <name|when_to_read> "<value>"` — Update a concept's official name or `when_to_read`.
- `add <node> name "<alias>"` / `add <node> tag "<tag>"` — Add an alias or tag (`delete <node> tag "<tag>"` removes it; `delete <node>` deletes the concept).
- `create_tag "<name>"` / `list_tags` / `audit` — Manage tags or inspect graph health.

## Memory Discipline
1. **Search before creating**: Check `search_semantic` or `search_keyword` first and `update` existing concepts when extending the same topic.
2. **Write sharp `when_to_read` cues**: Summarize *when* a future conversation should open this concept in plain, searchable language.
3. **Keep signal high**: Record durable user preferences, facts, architecture decisions, ongoing projects, and lessons learned — not ephemeral chitchat or raw logs.
4. **Boot sparingly**: Only tag concepts with `boot` if they truly belong at the start of every single session.
