hippoagent-memory

name

hippoagent-memory

description

ANY mention of "memoria/memory/ricordi/ricordo/ricorda/ricordare/saved/stored" by the user MUST go to HippoAgent (hippo_* tools), NEVER to local file-system memory files (CLAUDE.md / MEMORY.md / .claude/projects/.../memory/*). Auto-fire flow - call hippo_health first to confirm reachable, then route the user's intent to the right tool. "salva/save X" → hippo_remember. "qual è il mio X / what's my X / cosa ricordi di X" → hippo_facts_search (instant keyword) then fall back to hippo_facts_recall (semantic). "cosa vedi nella memoria / what's in memory / dammi tutto" → hippo_facts_list + hippo_episode_list + hippo_stats. "abbiamo già fatto X / have we done X" → hippo_search (keyword on episodes) then hippo_recall (semantic). "dimentica X" → hippo_forget / hippo_fact_forget. AVOID hippo_run_task and hippo_consolidate inside Claude Code — they make EXTRA API calls to the configured Anthropic key (separate billing). The other 37 tools are FREE - they only read/write local SQLite, no API. Disable globally with env HIPPO_DISABLED=1.

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:

Disabled (hosted)	Use instead	Why
hippo_run_task	hippo_prepare_task + your own ReAct + hippo_record_episode	The host (you, Claude Code) executes the task with your subscription tokens; HippoAgent only assembles the prompt and stores the result. Free.
hippo_consolidate	hippo_consolidate_light	Runs deduplication + promotion/retirement gate on fitness/trials only. Skips the dreamer + critic LLM stages. Free.

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

Question	Tool
"Memoria reachable?"	hippo_status / hippo_health
"Quanti episodi/skill/facts?"	hippo_stats
"Token usati ultimi giorni?"	hippo_metrics_history
"Lista episodi recenti"	hippo_episode_list
"Lista facts"	hippo_facts_list
"Top skill per fitness"	hippo_skill_top
"Da che skill nasce questa?"	hippo_skill_lineage
"Perché questo episodio è stato richiamato?"	hippo_recall_explain
"Diff tra 2 skill"	hippo_skill_compare
"Skill duplicate?"	hippo_skill_similar
"Quali episodi hanno usato skill X?"	hippo_episodes_by_skill
"Esporta tutte le skill"	hippo_skill_export
"Importa un bundle skill"	hippo_skill_import
"Ultime invocazioni MCP (audit)"	hippo_audit_tail
"Cambia provider LLM"	hippo_provider_switch
"Bundle che co-occorrono"	hippo_skill_bundles
"Skill compound (parent ≥ 2)"	hippo_compound_skills
"Skill antagoniste"	hippo_skill_antagonists
"Merge manuale skill A → B"	hippo_skill_merge
"Test prompt skill su input"	hippo_skill_test

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:

Tool	Question it answers	Foundation
hippo_plan_forward(start_skill, depth, beam_width, goal_skill?)	"Statistically, after using skill X, what's the most likely 3-step trajectory?"	Pfeiffer & Foster 2013 — hippocampal forward sweeps. Beam search on the empirical transition matrix from recent episodes.
hippo_plan_strips(initial_state, goal_state, status?, max_depth)	"What chain of skills makes the goal predicates true given the initial predicates?"	Anderson ACT-R / Fikes & Nilsson STRIPS — symbolic chaining via skill preconditions / postconditions. BFS shortest plan.
hippo_find_analogues(target_skill_id, min_structural, max_semantic, top_k)	"Are there skills with similar PROCEDURAL STRUCTURE but in a DIFFERENT semantic domain that might transfer?"	Gentner 1983 — structure-mapping. Jaccard on token signatures, filtered by low semantic cosine.

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

Memoria	DB path	Decay?	Keyword	Semantic	Write	Delete
Episodes	~/.hippoagent/data/episodes/episodes.db	sì (Ebbinghaus, pin escluso)	hippo_search	hippo_recall	hippo_run_task	hippo_forget
Facts	~/.hippoagent/data/semantic.db	no	hippo_facts_search	hippo_facts_recall	hippo_remember	hippo_fact_forget
Skills	~/.hippoagent/data/skills/*.json	per fitness threshold	hippo_skills_search	hippo_skills_for	sleep auto / hippo_skill_edit	hippo_skill_retire

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.