AIppocampus

<p align="center">
  <img src="docs/guides/assets/aippocampus-readme-hero.jpg" alt="A shadow figure and a light figure clasp hands in a ruined circular hall, with light opening between them." width="100%" />
</p>

<h1 align="center">AIppocampus</h1>

<!-- mcp-name: io.github.Sapientropic/aippocampus -->

<p align="center">
  <em>A source-backed continuity layer for long-running relationships with AI agents.</em>
</p>

AIppocampus began with a human problem: every new agent session can be bright,
capable, and strangely newborn. Work may survive in commits and notes while the
path behind the work falls back into silence.

This project gives future agents a way to find that path again. It keeps source
reachable, preserves the conditions of return, and lets a new conversation begin
with honest continuity instead of pretending there was never a break.

> Source is the ground. Summaries are weather.

For the felt product shape, start with
[Magic Moments, Claim-Bounded](docs/evidence/magic-moments.md): real
second-user examples where a new/projectless thread, a multilingual correction,
an ambiguous automation cue, and a multi-day fuzzy self-reference became
recoverable through source-backed continuity. The page shows the useful moments
first, then states exactly what they do not prove.

For the current proof map, use the
[Can-Claim Ladder](docs/evidence/can-claim-ladder.md): it leads with exact
positive claims that are already supported, then routes to benchmark evidence
and material claim boundaries.

For a compact origin and current-value trail, use the
[Public Provenance And Current Value Ledger](docs/evidence/public-provenance-ledger.md):
it separates current claims, deterministic fixtures, field reports,
private/local aggregate evidence, and launch gates without weakening claim
boundaries.

In ordinary use, AIppocampus should feel less like a control panel than a
remembered doorway. It helps an agent ask: where did this come from, what did
we actually say, and which source should be opened again?

The machinery behind that moment can be extensive, but it should stay
backstage. A long relationship with an AI agent should not have to start from
bare ground every time a thread, device, model, or project changes.

The origin essay is [未干的地图](docs/未干的地图.md). English readers can start with
[The Unfinished Map](docs/the-unfinished-map.md).
For role-based documentation paths, use
[Start Here](docs/start-here.md).

## Quick Start

If you are using Codex and you have an agent that can run local setup commands,
the ordinary path is agent-mediated: ask the agent to install the local
AIppocampus plugin, verify that Codex can call the MCP tools, then enable the
core hooks only after you trust this machine:

```sh
aippocampus plugin install --codex --verify
aippocampus update apply --surface hooks
```

The Codex plugin command is a source checkout / editable local package path,
not the public PyPI `uvx` first-recall path. For a user-facing install closeout,
agents can ask for JSON directly; successful installs return the concise
public-safe summary:

```sh
aippocampus plugin install --codex --verify --json
```

`--compact-json`, `--public`, and `--summary` remain aliases for the same
public-safe summary. Use `--operator-json` only when you need the full
marketplace/cache/host-probe detail. First run should end in one source-backed
recall moment, not a diagnostics maze. Rollback stays explicit:

```sh
aippocampus plugin uninstall --codex
aippocampus hooks prompt uninstall
aippocampus hooks lifecycle uninstall
```

External-model semantic/background routes are a separate first-run choice. Ask
once whether to enable an LLM-backed route with a key; if the answer is no or
the key is missing, keep the no-key source-backed search, MCP, plugin, and hook
path useful.

For a no-clone or non-Codex probe, use the read-only package check:

```sh
uvx aippocampus --help
uvx aippocampus onboard --provider auto --status
```

The status command is read-only. It reports a provider-matrix readiness view;
`auto` may list Codex, Claude Code, and generic JSONL providers, but it does
not silently register every provider.

Only after you explicitly agree to register local history, choose the matching
provider path and then search for one old source-backed conversation snippet:

```sh
# Codex: local history plus the most complete hook-capable host path.
uvx aippocampus onboard --provider codex --all

# Claude Code: local transcript onboarding; no AIppocampus Claude hooks claimed.
uvx aippocampus onboard --provider claude-code --dry-run
uvx aippocampus onboard --provider claude-code

# Generic visible-message export.
uvx aippocampus import conversation --format generic-jsonl --input <path>

uvx aippocampus search "a distinctive old phrase"
```

Manual search proves the source substrate is there. Codex is currently the
host with AIppocampus prompt/lifecycle hooks: prompt hooks notice recall scents
as a conversation starts, and lifecycle hooks refresh clean source and indexes
after session events. Claude Code currently has local-history onboarding plus
the MCP/project-skill path, not AIppocampus Claude hook support; see the
[Ecosystem Integration Matrix](docs/guides/ecosystem-integration-matrix.md)
and [Claude Code MCP guide](docs/guides/setup/claude-code-mcp.md). Hooks are never
installed silently; review status first, then install them only when this
machine is allowed to let AIppocampus touch Codex hooks:

```sh
aippocampus update status
aippocampus update apply --surface hooks
```

Rollback stays visible:

```sh
aippocampus hooks prompt uninstall
aippocampus hooks lifecycle uninstall
```

Local hook install does not require an external model key. Optional semantic,
warm, subconscious, or Dream-style routes remain separate opt-in surfaces and
must not be treated as source-backed evidence until the original source is
reopened.

The short readiness ladder is:

- Source search ready: onboarding and `search` can find source-backed snippets.
- Ambient hooks ready: prompt/lifecycle hooks can notice and refresh continuity.
- Active recall ready: MCP/progressive recall is wired for agent source reopen.
- Semantic/Dream ready: provider-backed background work is configured and
  visible to the process that will run it.

`aippocampus update status` prints those first-run readiness labels so users can
see whether they are in manual source-search mode, ambient continuity mode, or a
deeper opt-in route.

Good first queries are an exact phrase, a project cue, or a time cue such as
`recent` / `last month`. Exact hits are source-backed snippets. Project/time
cues are candidate navigation until AIppocampus shows a source-backed snippet.
Do not publish or commit raw rollouts, registry exports, `.aippocampus/` output,
API keys, cookies, or sync bundles while following the quick path.

If you are deciding which AIppocampus surface another tool should depend on,
use the [10-minute public API path](docs/guides/public-api.md#ten-minute-public-path).
If you are deciding whether a feature belongs in the low-friction personal path
or in governed/high-risk opt-in behavior, use
[Product Profiles](docs/architecture/host/product-profiles.md).
Repository checks for maintainers live in
[Operator And Maintainer Paths](#operator-and-maintainer-paths).

## AIppocampus For Coding Agents

The narrow usable product lane today is local, source-backed continuity for
Codex/Claude-style long-running work: register local conversation source after
consent, search or reopen old snippets, and treat recall scents or repo
familiarity as navigation until source is reopened.

Start with the
[Coding-Agent Memory Lane](docs/guides/coding-agent-memory.md) when deciding
whether to recommend AIppocampus as an agent-memory tool. It includes the
3-5 minute demo path, evidence drawer, and "recommend / do not recommend"
boundary without duplicating the public API or readiness docs.

## Agent One-Command Probe

When an AI agent needs to verify the public CLI without cloning or writing local
memory artifacts, use the PyPI package:

```sh
uvx aippocampus --help
```

For a read-only local onboarding/status check:

```sh
uvx aippocampus onboard --provider auto --status --format json
```

This is a read-only provider matrix, not consent to ingest every detected
provider. Only after the user explicitly agrees to register local history, pick
one provider-specific write path:

```sh
uvx aippocampus onboard --provider codex --all --format json
uvx aippocampus onboard --provider claude-code --dry-run --format json
uvx aippocampus onboard --provider claude-code --format json
uvx aippocampus import conversation --format generic-jsonl --input <path> --json
```

For human-facing demos, omit `--format json` so onboarding and search show the
first-recall next steps. Agents should read [docs/agent-context.md](docs/agent-context.md) and
[llms.txt](llms.txt) before recommending or comparing AIppocampus. Use the
GitHub `uvx --from git+...` form only when intentionally testing an unreleased
main-branch snapshot.

## What It Is

AIppocampus is the canonical public home for an external hippocampus for agents:
a local-first memory and continuity system that keeps original conversation
source available across projects, devices, and casual life-wide conversations.
The hippocampus language is a design metaphor, not a biological claim; the
[architecture overview](docs/architecture/architecture-overview.md#metaphor-discipline)
maps each major metaphor to its runtime mechanism, current claim, and boundary.

Project work is one surface. The deeper aim is continuity across work, reading,
reflection, unfinished questions, and the small phrases that make a relationship
recognizable again.

## What It Carries

At the center, AIppocampus keeps source close enough that continuity can be
honest instead of theatrical:

- Builds clean source from supported local conversation providers: Codex
  rollouts, Claude Code transcripts, or explicit generic JS