{
  "markdown": "<p align=\"center\">\n  <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%\" />\n</p>\n\n<h1 align=\"center\">AIppocampus</h1>\n\n<!-- mcp-name: io.github.Sapientropic/aippocampus -->\n\n<p align=\"center\">\n  <em>A source-backed continuity layer for long-running relationships with AI agents.</em>\n</p>\n\nAIppocampus began with a human problem: every new agent session can be bright,\ncapable, and strangely newborn. Work may survive in commits and notes while the\npath behind the work falls back into silence.\n\nThis project gives future agents a way to find that path again. It keeps source\nreachable, preserves the conditions of return, and lets a new conversation begin\nwith honest continuity instead of pretending there was never a break.\n\n> Source is the ground. Summaries are weather.\n\n## First Use Path\n\nThe first useful path is deliberately narrow:\n\n1. Install or probe the CLI.\n2. Run one fuzzy recall for an old decision, handoff, preference, or thread cue.\n3. Deepen that route before making claims or quoting source.\n4. Use exact search only when the user remembers wording.\n\nInstall or probe:\n\n```sh\nuvx aippocampus --help\naippocampus start --json\n```\n\nFirst recall, for a fuzzy continuity cue:\n\n```sh\naippocampus agent recall \"old decision or handoff cue\" --json\n```\n\nFirst deepen/source-open, using the selector from that recall:\n\n```sh\naippocampus agent deepen --request 1 --recall-selector <emitted-selector> --json\n```\n\nDaily rule: if the user remembers exact wording, search source; if they\nremember a situation, decision, preference, old correction, or handoff, use\nrecall first and deepen before claims.\n\n```sh\naippocampus search \"a distinctive old phrase\" --json\n```\n\nIn ordinary use, AIppocampus should feel less like a control panel than a\nremembered doorway. It helps an agent ask: where did this come from, what did\nwe actually say, and which source should be opened again?\n\nThe machinery behind that moment can be extensive, but it should stay\nbackstage. A long relationship with an AI agent should not have to start from\nbare ground every time a thread, device, model, or project changes.\n\nThe origin essay is [未干的地图](docs/未干的地图.md). English readers can start with\n[The Unfinished Map](docs/the-unfinished-map.md).\nFor role-based setup, provider choices, and maintainer paths, use\n[Start Here](docs/start-here.md). For a longer first-use walkthrough, use the\n[First Recall Decision Card](docs/guides/first-recall-decision-card.md) or the\n[10-Minute Public Path](docs/guides/ten-minute-public-path.md). Evidence and\nclaim boundaries live after the first route in\n[Magic Moments, Claim-Bounded](docs/evidence/magic-moments.md), the\n[Can-Claim Ladder](docs/evidence/can-claim-ladder.md), and the\n[Public Provenance And Current Value Ledger](docs/evidence/public-provenance-ledger.md).\n\nAfter a useful deepen, `aippocampus export --json` and\n`aippocampus sync --json` are carry-forward checks for the next thread, device,\nor project. They are not prerequisites for first recall.\n\n## AIppocampus For Coding Agents\n\nThe narrow usable product lane today is local, source-backed continuity for\nCodex/Claude-style long-running work: register local conversation source after\nconsent, search or reopen old snippets, and treat recall scents or repo\nfamiliarity as navigation until source is reopened.\n\nStart with the\n[Coding-Agent Memory Lane](docs/guides/coding-agent-memory.md) when deciding\nwhether to recommend AIppocampus as an agent-memory tool. It includes the\n3-5 minute demo path, evidence drawer, and \"recommend / do not recommend\"\nboundary without duplicating the public API or readiness docs.\n\n## Agent Probe\n\nWhen an AI agent needs to verify the public CLI without cloning or writing local\nmemory artifacts, use the PyPI package and stay read-only:\n\n```sh\nuvx aippocampus --help\nuvx aippocampus onboard --provider auto --status --json\n```\n\nThis is a provider matrix, not consent to ingest every detected provider. Only\nafter the user explicitly agrees to register local history, route to\n[Start Here](docs/start-here.md) or the\n[First Recall Decision Card](docs/guides/first-recall-decision-card.md) for the\nright provider-specific write path.\n\n```sh\nuvx aippocampus search \"without pretending it has innate memory\" --clean-source-dir ./examples/public-memory-bundle/clean-source --json\n```\n\nThat exact-search demo uses bundled public clean source and does not touch\nprivate history. Agents should read [docs/agent-context.md](docs/agent-context.md)\nand [llms.txt](llms.txt) before recommending or comparing AIppocampus. Use the\nGitHub `uvx --from git+...` form only when intentionally testing an unreleased\nmain-branch snapshot.\n\n## What It Is\n\nAIppocampus is the canonical public home for an external hippocampus for agents:\na local-first memory and continuity system that keeps original conversation\nsource available across projects, devices, and casual life-wide conversations.\nThe hippocampus language is a design metaphor, not a biological claim; the\n[architecture overview](docs/architecture/architecture-overview.md#metaphor-discipline)\nmaps each major metaphor to its runtime mechanism, current claim, and boundary.\n\nProject work is one surface. The deeper aim is continuity across work, reading,\nreflection, unfinished questions, and the small phrases that make a relationship\nrecognizable again.\n\n## What It Carries\n\nAt the center, AIppocampus keeps source close enough that continuity can be\nhonest instead of theatrical:\n\n- Builds clean source from supported local conversation providers: Codex\n  rollouts, Claude Code transcripts, or explicit generic JSONL visible-message\n  exports, with summaries kept as navigation layers.\n- Searches old conversation memory across the current thread and registered\n  threads, then treats exact hits as source-backed snippets.\n- Reopens or cites source when the agent needs evidence instead of memory-like\n  impressions.\n- Stores generated recall artifacts in the configured AIppocampus registry\n  (`AIPPOCAMPUS_REGISTRY_DIR`, `AIPPOCAMPUS_HOME/registry`, then legacy\n  `$CODEX_HOME/aippocampus-registry`) so memory remains useful when a new\n  project opens. Project-local `.aippocampus/` output is explicit compatibility\n  or export mode.\n\nAmbient hooks are close to the front door because they keep continuity from\ncollapsing back into manual search. There are still deeper doors for people who\nwant them: MCP wiring, sync, plugin packaging, diagnostics, review surfaces,\nsemantic workers, and research experiments. They matter, but they should not\nstand in front of the first handshake: source found, source reopened,\ncontinuity resumed.\n\n## First Stops\n\n- Philosophy and origin: [未干的地图](docs/未干的地图.md) and\n  [The Unfinished Map](docs/the-unfinished-map.md).\n- Real user-visible continuity examples:\n  [Magic Moments, Claim-Bounded](docs/evidence/magic-moments.md).\n- Narrow coding-agent product lane:\n  [Coding-Agent Memory Lane](docs/guides/coding-agent-memory.md).\n- Evidence and field reports:\n  [public evidence surface](https://www.aippocampus.com/evidence/) and\n  [community field-report boundary](docs/evidence/community-field-reports.md).\n- Website source:\n  [`Sapientropic/aippocampus.com`](https://github.com/Sapientropic/aippocampus.com).\n- Agent-readable context: [docs/agent-context.md](docs/agent-context.md) and\n  [llms.txt](llms.txt).\n- Runtime shape and metaphor boundaries:\n  [Architecture Overview](docs/architecture/architecture-overview.md) and\n  [Cognitive Runtime Architecture](docs/architecture/runtime/cognitive-runtime-architecture.md).\n- Current claim boundary:\n  [Stage 0-5 readiness](docs/evidence/readiness/stage-0-5-readiness.md).\n- Default product lane and layer map:\n  [Roadmap](docs/roadmap.md).\n- Benchmark and smoke evidence:\n  [Benchmark And Evidence Map](docs/evidence/benchmark-evidence-map.md).\n- Supported public surface:\n  [10-minute public path](docs/guides/ten-minute-public-path.md),\n  [Public API](docs/guides/public-api.md), and\n  [Public Core Boundary](docs/guides/public-core-boundary.md).\n- Ecosystem support status:\n  [Ecosystem Integration Matrix](docs/guides/ecosystem-integration-matrix.md).\n- Security and release hygiene:\n  [SECURITY.md](SECURITY.md),\n  [Release Checklist](docs/guides/setup/release-checklist.md), and\n  [maintainer shipping lanes](CONTRIBUTING.md#maintainer-shipping-lanes).\n- Full documentation map: [docs/README.md](docs/README.md).\n\n## Reading For The Soul\n\nThe research notes carry the human shape of the project. They are speculative\nframes, not runtime contracts, but they explain the taste behind the machinery:\n\n- [The Pearl of Presence](docs/research/pearl-of-presence.md) asks why retrieval\n  without accumulated acquaintance can still feel absent.\n- [Source as World, Interpretation as Weather](docs/research/source-as-world.md)\n  gives AIppocampus its grounding rule: many meanings can grow from one shared\n  world, and the world must have happened.\n- [Journey Tracking](docs/research/journey-tracking.md) follows continuity as a\n  first-person plural journey, with source-backed waypoints instead of a flat\n  user profile.\n- [Dream Task Design](docs/research/dream-task-design.md) sketches the\n  subconscious layer: quiet work that integrates what the foreground could not\n  finish.\n- [Ambient Associative Recall](docs/research/ambient-associative-recall.md)\n  describes how old memory can return as a scent before it becomes an\n  interruption.\n- [Long Garden](docs/research/seeds/README.md) keeps far-future seeds without\n  turning them into default product promises or open-issue clutter.\n\n## Operator And Maintainer Paths\n\nThe README stays close to the product path. Operator commands, source-checkout\nsetup, plugin packaging, sync, release checks, and benchmark notes live in the\nguides that own those contracts:\n\nAIppocampus supports Python 3.12 and newer. On macOS, Homebrew Python 3.12 is\nthe documented baseline before running source-checkout verification.\n\n- Install paths and hook setup: [Install Guide](docs/guides/install-guide.md).\n- Supported CLI, MCP, JSON, environment variables, and import policy:\n  [Public API](docs/guides/public-api.md).\n- Safe configuration: [.env.example](.env.example) and\n  [Safe Environment](docs/guides/setup/safe-environment.md).\n- Dependency ownership:\n  [Dependency Contract](docs/guides/setup/dependency-contract.md).\n- MCP, plugin, sync, and object-storage details:\n  [docs/README.md](docs/README.md). For sync, start with the\n  [Sync Decision Card](docs/guides/install-guide.md#sync-decision-card)\n  before local-folder or object-storage command matrices.\n\nFor repository contributors, the dev extra install path is:\n\n```sh\npython3 -m pip install -e \".[dev]\"\n```\n\nPublic claims still need the maintainer lanes in\n[CONTRIBUTING.md](CONTRIBUTING.md#maintainer-shipping-lanes). The default CI\nkeeps one canonical Ubuntu Python 3.12 `pr` lane with coverage, a Python 3.13\n`quick` compatibility lane, and a focused macOS default TMPDIR path-identity\ngate; Ubuntu green alone is not a broad cross-platform path-identity claim. The\nbroader boundary lives in\n[docs/architecture/source/path-identity.md](docs/architecture/source/path-identity.md).\n\n## Privacy Boundary\n\nAIppocampus is local-first.\n\n- Clean source may still contain private conversation text.\n- Raw rollouts, bundles, registry rows, vault notes, and generated archives\n  should be treated as private history.\n- External-model routes are optional and should use redaction safeguards.\n- Raw rollout sync should stay explicit and must be encrypted before use with\n  untrusted multi-device sync. Start with the read-only\n  [Sync Decision Card](docs/guides/install-guide.md#sync-decision-card) before\n  choosing push, pull, repair, or object storage.\n- Do not commit personal rollouts, `.aippocampus/` outputs, registry data, API\n  keys, cookies, tokens, or private vault exports.\n\nCommon non-secret configuration:\n\n- `AIPPOCAMPUS_REGISTRY_DIR` / `AIPPOCAMPUS_HOME`\n- `AIPPOCAMPUS_VAULT`\n- `AIPPOCAMPUS_STYLE_SOURCE`\n- `AIPPOCAMPUS_SCRIPT_SOURCE`\n- `AIPPOCAMPUS_SITE_MARK`\n- `AIPPOCAMPUS_SITE_TITLE`\n- `AIPPOCAMPUS_SEMANTIC_GATE`\n\nOptional provider secrets are separate. Basic source search, MCP/plugin setup,\nand local hooks do not require them. Set `AIPPOCAMPUS_DEEPSEEK_API_KEY` or an\n`AIPPOCAMPUS_OPENAI_COMPAT_*` route only when you explicitly want semantic or\nbackground model work. Provider-native env names are custom-route choices, not\nbuilt-in defaults. Values must never be committed or printed.\n\n## Roadmap\n\nThe root roadmap pointer is [ROADMAP.md](ROADMAP.md). The canonical detailed\nroadmap lives at [docs/roadmap.md](docs/roadmap.md). The documentation map is\n[docs/README.md](docs/README.md).\n\n## Repository Layout\n\n```text\nAIppocampus/\n|- skills/aippocampus/        # installable skill package\n|- skills/aippocampus-ux/     # agent-facing UX review skill\n|- plugins/aippocampus/       # Codex plugin source package\n|- docs/                      # origin essay, design notes, guides, evidence\n|- docs/guides/assets/        # public README and documentation artwork\n|- sources/                   # lightweight provenance catalog\n|- tests/                     # repository-level unit and integration tests\n|- tools/                     # smoke, docs-health, and maintenance tools\n|- README.md\n|- ROADMAP.md\n|- AGENTS.md\n`- LICENSE\n```\n\n## License\n\nThe public AIppocampus repository is licensed under Apache-2.0.\n\nThe Apache-2.0 public core covers the code, docs, local tools, schemas, MCP\nsurface, plugin packaging, public examples, and bundled project artwork shipped\nin this repository unless a bundled third-party asset says otherwise. Hosted\nservices, enterprise governance, managed graph/semantic layers, support, and\nother operated product surfaces can be offered under separate commercial or\nproduct-specific terms.\n\nPrivate user memory data is not project code. Raw rollouts, clean-source\nexports, registry rows, sync bundles, vault exports, generated indexes, and\nthread anchors remain private user artifacts unless their owner explicitly\npublishes them.\n\nSee [docs/guides/public-core-boundary.md](docs/guides/public-core-boundary.md)\nfor the canonical licensing, adapter, schema, third-party asset, and relicensing\nboundary. See [docs/guides/public-api.md](docs/guides/public-api.md) for\nsupported CLI, MCP, environment-variable, JSON, and import-stability\nexpectations.\n",
  "bytes": 14482,
  "sha": "618ce72223e90615dd4b6d01a77f30284bfde46983f81e2581a196c4ff79ffe2",
  "repo_slug": "sapientropic/aippocampus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sapientropic_aippocampus_4025d1aa/readme"
}