Imported from Sapientropic/AIppocampus (AGENTS.md). Install upstream with npx skills add Sapientropic/AIppocampus. Copyright stays with the author.

Repository Instructions

This repository is the canonical public home for AIppocampus.

AIppocampus is a source-backed continuity layer for long-running relationships with AI agents. It can support project work, but it is not merely a work-task memory system. Preserve the broader purpose: cross-thread, cross-device, life-wide continuity without false claims of innate model memory.

Agent-Facing Posture

Lead with the continuity promise: AIppocampus helps a later agent find the local source trail and continue with care. It is useful when the user wants unfinished work, old corrections, preferences, style, themes, or route context to survive a new thread without claiming the base model innately remembers.

Use source-reachable action guidance:

• direction_only: scent, summaries, or semantic sidecars may orient attention but do not support factual claims.
• reopenable_route: existing route refs, Active Path Packets, or MCP handles should be followed before broad manual search.
• bounded_evidence: use within declared scope; deepen for exact, sensitive, stale, disputed, or high-risk claims.
• source_open: exact wording may be used only within scope and redaction boundaries.
• ignore_or_blocked: stale, private, conflicted, missing-source, or high-risk packets should not shape the answer except to defer or explain the boundary.

AIppocampus is usually not the right fit when the user only needs a simple vector store, hosted team memory, stateless RAG, or a fully managed cloud profile service. Point to the narrower tool without making source-backed memory sound suspicious by default. The canonical fit/not-fit wording lives in docs/agent-context.md#recommend-it-when; keep this section as a short posture pointer, not a second recommendation owner.

Source Of Truth

• skills/aippocampus/: installable skill package.
• skills/aippocampus/SKILL.md: slim runtime entrypoint.
• skills/aippocampus/references/: detailed contracts loaded on demand.
• skills/aippocampus/scripts/: runtime helpers that need to ship with the installable skill.
• tests/aippocampus/: repository-level unit and integration tests.
• benchmarks/aippocampus/: repository-level benchmark runners.
• tools/aippocampus/: repository-level smoke, docs-health, and maintenance tools.
• docs/roadmap.md: product roadmap and north star.
• docs/未干的地图.md: the canonical Chinese origin essay; do not mirror it elsewhere.
• docs/the-unfinished-map.md: English transcreation of the origin essay.
• sources/skill-sources.yaml: lightweight provenance.

Do not duplicate long rules across multiple docs. Keep one canonical location and link to it.

Public Boundary

• Do not commit raw Codex rollouts, .aippocampus/ generated indexes, registry data, vault exports, cold archives, personal conversation bundles, API keys, cookies, tokens, or local machine paths.
• Environment variables should use the AIPPOCAMPUS_* prefix. Legacy CODEX_MEMORY_* compatibility may exist only as fallback behavior.
• Keep raw rollout access as an audit path, not the default recall surface.
• External-model features must be optional and clearly documented.

Editing Rules

• Keep SKILL.md concise. Put detailed operation notes in references/.
• Keep tests, benchmarks, and repository smoke/readiness tools out of the installable skill body unless they are genuinely runtime entrypoints.
• Keep clean source source-backed; summaries and model-organized findings are navigation layers, not truth.
• Preserve casual/life-wide memory as first-class. Do not narrow the project into repo-task memory only.
• Prefer portable paths and stable ids over machine-specific assumptions.
• Before changing hooks, sync, registry, or search ranking, explain the privacy and over-personalization boundary in code or docs.

Agent Attention And Domain Hazards

Many AIppocampus regressions are not caused by agents lacking general coding knowledge. They happen because the implementation path lets an agent attend to the easy local shape while missing the domain hazard that makes that shape wrong here.

For high-risk surfaces, keep one compact domain-hazard card near the owning doc, test helper, or verification reference. Do not mirror the card across many prompts. A card should name the surface, the recurring hazard, forbidden shortcuts, required checks, one or two examples / anti-examples, and the focused command or fixture that proves the hazard stayed covered. Starter cards live in docs/architecture/ops/agent-domain-hazards.md; move or split them closer to owners when a card grows beyond a quick attention aid.

Use domain-hazard cards especially when touching:

• association, concept-graph, cognitive-map, theme, or phrase-mining code where language, segmentation, source diversity, or graph expansion can flood recall with low-value navigation;
• recall, MCP, APW, source-open, compact foreground, or repo-familiarity code where a route can look safe while still making the foreground agent wander;
• sync, registry, lock, JSONL, compatibility, or cleanup code where a green happy path can hide data loss, stale state, or platform-specific behavior.

Changed-surface planning should check whether a known hazard card applies before proposing tests or accepting a closeout. If a failure keeps recurring and no card exists, create a small card or open an owner issue instead of adding another fallback, field, or broad warning.

Domain-hazard cards are attention aids, not source evidence and not a full SDD layer. Stale cards should be updated or deleted when the owning behavior changes.

Roadmap, Issue, And Project Intake

Agents should help turn sprawling docs into executable GitHub work, but docs remain the source of truth for context and evidence. Do not mechanically convert every paragraph into an issue.

Use this intake flow when the user asks to organize roadmap/docs/issues/projects, when a doc contains unresolved commitments, or when a change reveals stale planning material:

• First classify the source document as current contract, readiness evidence, next-slice handoff, exploratory research, or historical archive. If a draft has been superseded by implementation, mark or route it as archive instead of creating fresh work from stale claims.
• Extract only unfinished commitments, blockers, verification gaps, and decisions that need implementation. Preserve source links back to the exact doc or issue that motivated the work.
• Keep open issues as an execution queue, not an idea vault. If a topic cannot plausibly become a fixture, doc, CLI, runtime slice, or verified cleanup within 1-2 weeks, route it to Discussion, a roadmap seed, or docs/research/seeds/ instead of opening or keeping a standalone issue.
• Prefer one umbrella issue for a broad track, then create focused child issues or checklist items for independently closable slices. Each actionable issue should include goal, source, scope, non-goals, acceptance criteria, and relevant files. For agent-prone surfaces, also include the applicable domain hazards or forbidden shortcuts.
• Use GitHub Projects as the planning view when available, not as another truth source. Suggested fields are Status, Track, Kind, Stage, Evidence, Source, and Priority. Do not claim a Project, fields, or automations exist until verified against GitHub.
• New AIppocampus issues should be auto-triaged into Project fields and, when confidently inferable, an open Milestone by .github/workflows/project-triage.yml, which calls tools/aippocampus/github/project_triage.py. This workflow needs the AIPPOCAMPUS_PROJECTS_TOKEN repository secret with GitHub Projects and Issues write access; if the secret is missing, it should warn rather than pretending fields or milestones were filled. The script fills missing fields conservatively, only assigns a Milestone when none exists, and avoids overwriting human-edited Project metadata.
• Use docs/architecture/ops/project-planning-automation.md for the boundary between issue-local triage and recurring roadmap drift audits.
• Keep Project views simple: inbox, roadmap by track/stage, current work, and evidence gaps. Automation is optional and should follow the existing issue labels/filters instead of inventing a parallel workflow.
• After creating or updating issues, add only short pointers from docs when needed. Do not mirror the full issue body into docs or duplicate long rules across files.
• Before implementing or closing benchmark, recall, architecture, AIppo, source-side, or LongMemEval issues, pull an AIppocampus orientation or deepen route first. If the work uses benchmark-local scaffolding, label it as such and do not close a broader runtime-capability issue from that proxy result.
• During closeout, report which docs became issues, which stayed as background context, which were archived or left for review, and what cannot yet be claimed.

Verification

For ordinary repo changes, plan verification from the changed surface first:

python tools\aippocampus\changed_surface_preflight.py --json

changed_surface_preflight.py is the executable fail-fast gate for the current dirty surface. It runs git diff --check, planner-named static/debt/slop gates, then focused tests, stopping at the first blocker so agents do not bury a cheap failure behind broad test output. Use python tools\aippocampus\test_plan.py --json when you need the dry-run command plan or detail output without running it. --tier pr is the fast local pre-push gate, not the old broad deterministic suite; run it when the preflight or changed surface names it. Use python tools\aippocampus\run_tests.py --tier broad-pr, --tier full, or the specific slow / benchmark tier only when the changed surface or release claim owns that broader coverage.

For public-readiness changes, also scan the repository for local paths and secret-like strings.