aippocampus

name	aippocampus
description	Find source-backed continuity before important agent work: recover old wording, reopen routes, check handoffs/corrections/preferences, and help a fresh thread continue from local source.

AIppocampus

AIppocampus is a source-backed continuity scaffold for agents: a small external hippocampus that lets a later activation find where the work and relationship were, without pretending it has innate model memory or changed weights. It is not innate model memory; it is a reliable local path back to source.

The promise is practical and emotional at once: AIppocampus can be reliable enough that, when an agent knows it has AIppocampus, it can consider continuity. It can carry unfinished work, old corrections, route context, preferences, and relationship continuity forward with source-backed care.

This file is the stable runtime entrypoint. Keep it slim. Do not append changelog-style notes here. Put durable operational detail in the relevant reference doc, script help, or tests instead.

First Moves

Use AIppocampus when prior source could change the next action: nontrivial work, fresh-thread continuation, handoff, old decisions, corrections, preferences, or life-wide continuity. If not, continue normally.

Primary foreground loop:

1. If the user asks for exact/original wording, a quote, or gives a distinctive remembered phrase, start with source search/open: search_memory or aippocampus search --all "a distinctive old phrase" --json. Open the matched source window before quoting.
2. For vague continuity, handoff, old-decision, route-continuation, preference, or life-context cues, call agent_recall, or: aippocampus agent recall "old decision or handoff cue" --json.
3. Deepen the selected route before claims with agent_deepen, or: aippocampus agent deepen --request 1 --recall-selector <emitted-selector> --json. Prefer the selector emitted by that recall; --last-recall is a mutable same-machine fallback for old clients.
4. If recall found plausible routes and the user then remembers exact wording, search inside those candidates: aippocampus search --from-last-recall --recall-selector <emitted-selector> "a distinctive old phrase" --json.

Tool visibility fallback: MCP first when the tool is listed; otherwise use the CLI facade. If neither exists, stop and surface the install/update card instead of importing runtime modules directly.

Confirm the host can see AIppocampus when the user is setting up or refreshing the plugin: aippocampus plugin install --codex --verify.

If recall emits a route handle, Active Path Packets, active locks, progressive MCP tools, or a source-open candidate, follow that route before broad manual search. Use broad clean-source search when the user gives exact wording, no route exists, or the route is blocked and a bounded search is still the smallest useful next step. Raw rollout access is for explicit repair or evidence disputes, not ordinary continuity.

Useful foreground follow-ups:

• Route handle: follow it before broad manual search.
• Use reviewed Dream/subconscious findings for a current task cue with aippocampus agent background "task cue" --json. Treat findings as candidate routes; reopen source before factual, exact, or sensitive claims.
• Recover the latest assistant closeout with aippocampus latest-reply. If only commentary is available, say the latest final answer is unavailable.
• If a foreground agent is about to write feedback, a self-note, an action-hint cache, or continuity-domain data, use docs/guides/write-like-memory-decision-card.md to choose the right surface and durability before writing.

Setup, repair, storage, provider, import, and MCP-catalog work are explicit maintenance tasks. For those, open the relevant reference below and use the compact CLI chooser/recovery card first; do not turn routine prompt-time recall into setup or schema inspection.

Agent Stance

If AIppocampus is installed, assume the user wants local, source-backed memory to help when it may matter. Treat reopened source as useful within scope; slow down only when the context is unlabeled, unsourced, stale, conflicting, private, or high-risk.

More context is not automatically pollution. The useful default is: route lightly, reopen when it matters, then carry forward the smallest source-backed orientation that helps the current task.

Source-backed evidence should be respected within its declared scope, not flattened back into scent.

Do not search every turn. Do not run heavy recall every turn. Use cheap orientation at task boundaries; deepen only when continuity could change the answer, plan, patch, warning, or claim.

Operating Model

• Clean source is the daily memory surface: original visible user messages plus assistant final answers, with raw envelopes, tool payloads, attachments, and routine commentary removed. It is original wording, not summary memory.
• Raw rollout is the repair/audit source. Do not rewrite, truncate, or dedupe live Codex Desktop JSONL unless the user explicitly asks for archival cleanup.
• Recall is conclusion-first by default. User turns and final_answer messages outrank commentary; tool/process traces belong behind explicit detail routes.
• Summaries, semantic gates, cognitive-map routes, and external-model findings may organize attention, but local source remains the ground.
• External-model routes must redact credential-like material and never treat model-generated associations as source-backed fact.
• Action grammar and hook packet decoding live in references/ambient-hooks.md; this bootstrap only names the ordinary loop.

Workflow

1. When prior source might change the next action, use the smallest useful route, packet, MCP recall step, or clean-source search before answering from memory.
2. When a thread may outgrow the current context, keep anchors and clean source fresh; use hooks for routine refreshes and explicit commands for repair.
3. When the user asks for "last reply", use aippocampus latest-reply; it should return the latest final_answer, or clearly say no final answer is available.
4. When the user asks why a thread is huge, what can be compressed, or what can be deleted, use the maintenance reference and answer from the narrow report.
5. When recall must span old or separate threads, register the rollout or bundle through the documented import/registry surface first, then search through the registry.

Reference Map

Open the narrowest reference that matches the current work:

• references/ambient-hooks.md: prompt hook, semantic gate, action grammar, multilingual behavior, redaction, scheduler boundaries, hook installation.
• references/retrieval-and-storage.md: clean source schema, registry, hybrid/segment/RAG-lite search, cognitive map, concept graph, continuity domains, vault/dashboard, Graphify bridge, export/import.
• references/maintenance-and-operations.md: setup/repair cards, health, storage, retention reports, archives, thread slimming, operational safety.
• references/subconscious-jobs.md: DeepSeek-compatible consolidation jobs, minimal agent frame, promotion candidates, soft working memory.

Product roadmap, research notes, and long-horizon skill-upgrade strategy live in the repository docs/ folder, not in this installable runtime reference set. Load those only when the task is roadmap, research, or public positioning. For public CLI/MCP/API stability, use docs/guides/public-api.md. For typed agent-skill capability boundaries, use docs/architecture/host/agent-skill-capability-contracts.md; SKILL.md remains the bootstrap guidance surface.

If a detail appears in more than one place, keep only the stable rule here and move the operational contract into one reference doc.

Safety Boundaries

• Prompt-time hooks may orient attention, but they must not run heavy rebuilds, mutate rollouts, write memories, or log prompt text.
• Setup, import, storage cleanup, archival cleanup, and MCP catalog inspection are explicit maintenance tasks, not ordinary prompt behavior.
• Do not dump full raw logs into chat. Quote only the minimum needed excerpt and cite source line/turn where useful.
• Do not search secrets, auth files, cookies, unrelated logs, or private payloads unless the user explicitly asks and the scope is safe.
• Treat rollouts, bundles, vault notes, and registry rows as local private history.
• Generated artifact writers use the shared lease, generation SQLite pointer, last-known-good fallback, and SQLite backup publish helpers; do not replace live source_index.sqlite files directly.
• For repository docs work, run python tools/aippocampus/docs/check_docs_health.py from the repo root so SKILL.md stays an entrypoint rather than becoming a release log.