Hippoagent Memory

HippoAgent Persistent Memory — auto-recall skill (v5 — 75 tools)

This skill makes Claude Code automatically use HippoAgent's hippocampal memory system across sessions. HippoAgent is a plug-in MCP server that exposes 75 tools covering 3 memory tiers (episodes, facts, skills) PLUS 3 reasoning tools (forward planning, STRIPS, structural analogy) PLUS 26 introspection/curation tools (skill_health, recommend_actions, predicate_graph_check, curate_pipeline, etc).

⚠️ CRITICAL: "memoria" = HippoAgent, NOT local files

When the user says any of these:

• "memoria", "memory"
• "ricordi", "ricordo", "ricorda", "ricordare"
• "saved", "stored", "salvato"
• "cosa sai di...", "what do you know about..."
• "cosa hai in memoria", "what's in memory"

→ You MUST query HippoAgent (hippo_* tools). → Do NOT read ~/.claude/projects/*/memory/*.md or CLAUDE.md files unless the user explicitly says "leggi il file CLAUDE.md" or "open the local memory file". Those local files are Claude Code's own auto-memory layer — separate, less rich, and not what the user is asking about when they say "memoria".

⚠️ Cost note: HOSTED MODE inside Claude Code

When running inside Claude Code (the default — ~/.mcp.json sets HIPPO_HOSTED=1), HippoAgent never calls an external LLM API. Every cost stays on Claude Code's subscription tokens.

The 2 tools that would make extra API calls (hippo_run_task, hippo_consolidate) are disabled in hosted mode and return an error pointing to their free equivalents:

The other 39 tools are read/write on local SQLite — zero API cost.

To run the full sleep cycle (with dreamer + critic, requires LLM) ask the user explicitly. Only then unset HIPPO_HOSTED for that one call, or run hippo consolidate from the CLI outside Claude Code.

Activation flow

Always, at the start of every conversation:

1. Call hippo_health (deeper preflight, single call) to verify the memory layer is reachable. If it returns status: degraded, tell the user the layer is partially offline (the rest of Claude Code still works).

2. For each user message, decide which tool(s) to call based on the routing table below. Always do the read BEFORE answering so the response is grounded in the user's persistent memory.

3. After learning a new fact from the user, store it via hippo_remember (free, no API call, persistent across sessions). Do NOT call hippo_run_task to "record" the conversation — that spawns a separate agent + costs API calls.

4. Do not auto-call hippo_consolidate. The user will request it explicitly when they want a sleep cycle (e.g. "consolida adesso").

Routing table — natural-language intent → tool

"Save / store / remember this fact"

User says: "salva che X", "ricordati che X", "my email is X", "il mio account è X", "the API endpoint is X".

→ Call hippo_remember with {proposition, topic?, confidence?}. Writes directly to semantic memory (semantic.db), persistent across sessions, no decay. Confirm: "Saved. Fact id: X".

"Recall / what do you know about X"

User says: "qual è il mio account?", "what's the API endpoint?", "ricordi qualcosa su X?".

→ First hippo_facts_search(query=X) — keyword LIKE on facts, instant (no embedding cold start). If 0 hits, fall back to hippo_facts_recall(query=X) — semantic cosine.

"Have we done this task before?"

User says: "abbiamo già fatto X?", "have we built X before?", new feature request that might overlap with prior work.

→ First hippo_search(query=X) — keyword LIKE on episode task_text, instant. If 0 hits, fall back to hippo_recall(query=X) — semantic cosine on episode embeddings.

"Show / get the details of episode Y"

User says: "dammi i dettagli dell'episodio Y", "show me episode Y".

→ Call hippo_episode_get(episode_id=Y) — full ReAct trajectory.

"Forget / delete / cancella X" (privacy / GDPR)

User says: "dimentica che X", "delete this", GDPR request.

→ For an episode: hippo_forget(episode_id=Y). → For a fact: hippo_fact_forget(fact_id=Z). → For a skill: hippo_skill_retire(skill_id=W).

"Pin / protect this episode forever"

User says: "non dimenticare mai X", "questo è importante".

→ Call hippo_episode_pin(episode_id=Y) so the episode is excluded from decay-pruning regardless of Ebbinghaus retention. → To release: hippo_episode_unpin(episode_id=Y).

"What skills do you have for X / cosa sai fare X"

→ First hippo_skills_search(query=X) — keyword on skill name+trigger+body. If 0 hits, hippo_skills_for(task=X, k=3) — semantic preview of which skills HippoAgent would inject. → For a 1-line summary: hippo_skill_describe(skill_id=W).

"Cosa vedi nella memoria? / What's in memory?"

User says: "cosa vedi nella memoria", "what do you have", "dammi tutto quello che sai", "show me everything you remember".

→ Run all three in parallel and combine:

• hippo_stats for counts (episodes / skills / facts / token usage).
• hippo_facts_list(limit=20) for the latest declarative facts.
• hippo_episode_list(limit=10) for the latest episodes.

Present the combined result. Do NOT read CLAUDE.md or ~/.claude/projects/*/memory/MEMORY.md — those are Claude Code's own local memory, not HippoAgent's. The user almost certainly means HippoAgent.

"Esegui questo task / Run this task with memory" (HOSTED mode)

Inside Claude Code, never call hippo_run_task — it's disabled when HIPPO_HOSTED=1 (the default in ~/.mcp.json). Instead, use the free 2-step flow:

1. hippo_prepare_task(task=<the user's request>, k_skills=3, k_episodes=3) → returns {skills, recall, rendered_prompt, llm_called: false}. This is the relevant context from memory — past episodes that look similar, consolidated skills that might apply, an assembled prompt.
2. You (Claude Code) execute the task using your normal flow, informed by the context returned in step 1. Your subscription tokens pay the cost.
3. hippo_record_episode(task_text=..., final_answer=..., outcome=..., skills_used=[...], tokens_used=N) to persist the result so future sessions can recall it.

Same for sleep cycles: hippo_consolidate is disabled in hosted mode; use hippo_consolidate_light instead — it does dedup + promote + retire without any LLM call. The full dreamer/critic cycle stays optional and explicit.

Maintenance / dashboards / introspection

Reasoning on novel/composite tasks (Pezzo A+B+C)

When the task is new or composite (multi-step, doesn't match any single skill semantically), don't just call hippo_recall and hope. Combine the 3 reasoning tools:

Composition pattern. For an unfamiliar task:

1. hippo_recall(task) — semantic retrieval (existing).
2. If recall is thin, hippo_find_analogues(top_skill_id) — surface structurally-similar skills the semantic search missed.
3. If you have explicit pre/post for the goal, hippo_plan_strips — chain skills by symbolic preconditions.
4. If you have a starting skill but no explicit goal predicates, hippo_plan_forward(start_skill, depth=3) — see the most likely 3-step trajectory and pick the branch that fits.

All three are PURELY LOCAL — no LLM call, ms-scale, free in HOSTED mode. They give Claude Code 3 different "lenses" on the skill library so the host LLM can pick its move with more information than just "top-1 semantic match".

Memory layout

The 3 stores are independent SQLite/JSON; durable, atomic, no external dependencies. Restarting Claude Code, rebooting the machine, moving to a new project — none of those reset memory.

Why this matters

Without this skill, every Claude conversation starts from zero. With it:

• The agent remembers facts you told it 5 sessions ago (your email, codebase conventions, prior bug fixes).
• The agent reuses skills it learned in prior sessions (compiled macros bypass the LLM entirely on recurring task families).
• The agent scales compositively — recombining 2 or 3 atomic skills on a new compound task.

Empirical performance (committed bench data, real LLM calls)

• Compositional generalization: raw LLM 25-42%, HippoAgent 100% on Anthropic / DeepSeek / OpenRouter (4-provider sweep, Lv1-Lv5).
• Held-out practical tasks (URL parsing, date format, capitalize, reverse, word count): 5/5 TRAIN + 5/5 HELD-OUT on Anthropic Opus 4.7.
• Learning curve: token cost from 4225 (cold) → 0 at iter 3+ (compiled-macro fast-path, 70% hit rate after consolidate).

Disabling

To disable temporarily without uninstalling, set env var HIPPO_DISABLED=1 before launching Claude Code. The MCP server exits immediately on startup; the rest of Claude Code is unaffected.

Configuration tips

# Persistent data dir (default: ~/.hippoagent/data)
export HIPPO_DATA_DIR=~/.hippoagent/data

# Force a specific LLM provider
export HIPPO_LLM_PROVIDER=anthropic   # or openai|openrouter|groq|deepseek|ollama|xai

# Enable advanced neuroscientific mechanisms (default off — safe)
export HIPPO_BUNDLE_DISCOVERY_ENABLED=1
export HIPPO_NEGATIVE_BUNDLE_ENABLED=1
export HIPPO_SYNAPTIC_TAGGING_ENABLED=1
export HIPPO_CROSSOVER_ENABLED=1

# Auto-fallback across providers if rate-limited
export HIPPO_AUTO_FALLBACK=1

Privacy

All memory lives in local SQLite/JSON files under HIPPO_DATA_DIR. No data is sent to remote servers other than the LLM provider's standard API. The skill library is plain JSON; user can inspect and edit at any time. GDPR-symmetric: every memory tier has a forget tool.