hippo-memory

name	hippo-memory
description	Biological memory for the agent. Use when: observing facts worth persisting | recalling prior context | reacting to errors | making architectural decisions | resolving conflicts. Triggers: "remember" | "recall" | "i learned" | "we decided" | "the issue was" | "never do X" | "always do Y".
version	0.1.0
allowed-tools	tff-memory_remember, tff-memory_recall, tff-memory_context, tff-memory_decide, tff-memory_outcome, tff-memory_pin, tff-memory_forget, tff-memory_invalidate, tff-memory_conflicts, tff-memory_resolve, tff-memory_inspect, tff-memory_wm_push, tff-memory_wm_read, tff-memory_status, tff-memory_share

Hippo Memory

Bio-inspired. Decay default; persistence earned.

Let:

μ     := memories (project ∪ global)
ε(m)  := m ∈ episodic (decays)
σ(m)  := m ∈ semantic (stable)
β(m)  := m ∈ working-memory (session, no decay, |β| ≤ 20)
s(m)  ∈ [0,1]          — strength
h(m)  ∈ ℝ₊             — half-life (days)
r(m)  ∈ ℕ              — retrievals
c(m)  ∈ {verified, observed, inferred, stale}
v(m)  ∈ {neutral, positive, negative, critical}
π(m)  ∈ 𝔹              — pinned
q     := current query
τ_b   := 1500          — context budget (tokens)
τ_r   := 5             — recall limit

Axioms

A₁  s(m) = base · 0.5^(Δt/h_eff) · boost_r · mult_v
A₂  retrieve(m) → r++ ∧ h += 2 ∧ (c=stale → c←observed)
A₃  outcome(m, good) → pos++ ∧ h_eff · (1 + 0.5·reward_ratio)
A₄  outcome(m, bad)  → neg++ ∧ h_eff · (1 − 0.5·|reward_ratio|)
A₅  π(m) → h(m) = ∞
A₆  error-tagged m → h(m) · 2 ∧ s(m) · 1.5
A₇  decide(d) → h(d) = 90 ∧ c(d) = verified

Predicates

should_remember(x) ⟺ ¬derivable(x, repo) ∧ ¬documented(x, CLAUDE.md) ∧ (surprising(x) ∨ error(x) ∨ decision(x) ∨ correction(x)) ∧ specific(x)

should_recall(q) ⟺ context_auto_inject ∉ active_turn → (q mentions prior ∨ q references "last time" ∨ ambiguity ∃)

should_capture_error(e) ⟺ ¬duplicate(e, 60s) ∧ extractable_lesson(e) ∧ |e| < 500

should_decide(d) ⟺ architectural(d) ∧ long_term(d) ∧ ¬ephemeral_workaround(d)

should_pin(m) ⟺ critical(m) ∧ (¬survivable_via_earning(m) ∨ user_request)

should_invalidate(p) ⟺ ∃ migration: old→new ∧ |matches(μ, p)| > 0 ∧ ¬recent_decay_handles(p)

Operations

O_capture(x, tags) {
    should_remember(x) → tff-memory_remember(content=x, tags=tags, kind=observed)
    ¬should_remember(x) → ∅
} → m_id ∨ ∅

O_capture_error(e) {
    should_capture_error(e) → tff-memory_remember(content=summary(e,200), tags=["error", topic(e)], error=true)
} → m_id ∨ ∅

O_capture_decision(d, ctx, supersedes?) {
    should_decide(d) → tff-memory_decide(decision=d, context=ctx, supersedes=supersedes)
} → d_id ∨ ∅

O_recall(q, budget?) {
    τ := budget ∨ τ_b
    R := tff-memory_recall(query=q, budget=τ, limit=τ_r, why=true)
    |R| = 0 → ∅
    |R| > 0 → integrate_observations(R)
} → R

O_react_to_conflict(c) {
    φ := tff-memory_inspect(id=c.first); γ := tff-memory_inspect(id=c.second)
    κ := resolve_by_confidence(φ, γ)
    tff-memory_resolve(conflictId=c.id, keep=κ)
} → resolved

O_end_of_turn_feedback(anchorId, success: 𝔹) {
    success → tff-memory_outcome(anchorId, good)
    ¬success → tff-memory_outcome(anchorId, bad)
} → signal_propagated

Tool Triggers

Event	Tool	Note
∃ user correction	tff-memory_remember + tag correction	≤200 chars
∃ tool error	auto-captured; manual if extraction failed	see O_capture_error
∃ architectural decision	tff-memory_decide	90-day half-life
"do we have X?"	tff-memory_recall	scope=both default
"when did we X?"	tff-memory_recall + why=true	show match exp
"forget X"	tff-memory_forget or tff-memory_invalidate	forget=id, invalidate=pattern
conflict surfaced	tff-memory_resolve	after inspect both
ongoing task start	tff-memory_wm_push(scope=task_id, ...)	bounded, no decay
pin critical	tff-memory_pin(id, pinned=true)	h = ∞
migration X→Y	tff-memory_invalidate(pattern=X)	weaken old refs

¬do

¬tff-memory_remember for: code patterns | file paths | project structure | git-derivable | CLAUDE.md contents | ephemeral state | chit-chat

¬tff-memory_recall preemptively if before_agent_start already injected context (check "Prior observations (hippo memory...)")

¬pin memories that can earn strength through retrieval (pinning = escape hatch)

¬duplicates — recall returns match → tff-memory_outcome(good) instead of new entry

¬resolve conflicts without inspect

Framing

Recalled memories presented as observations, not commands:

"Previously observed (2026-03-14, verified, s=0.82): auth middleware stored session tokens insecurely; replaced with argon2id + jwt rotation."

Agent treats memories as context. Contradiction → tff-memory_inspect → decide:

• stale → tff-memory_invalidate(pattern)
• wrong → tff-memory_forget(id)
• right, task wrong → ask user

Outcome feedback loop

before_agent_start → retrieve context → anchorId
turn_end → success ⟺ (¬errors in last 3 tool_results) ∧ (stop_reason = "stop")
success → tff-memory_outcome(anchorId, good)
¬success → tff-memory_outcome(anchorId, bad)

Reward propagates via apply_outcome: good → extend h_eff; bad → weaken.

Store scope

∀ m ∈ μ: m.root ∈ {project, global}
project  := .pi/hippo-memory/hippo.db
global   := ~/.pi/hippo-memory/hippo.db
default recall: both
promotion: auto during sleep when transfer_score(m) > threshold
manual: tff-memory_share(id)

¬touch

frontmatter | allowed-tools | hippo internal tables (memories, memories_fts, consolidation_runs, memory_conflicts) | .pi/hippo-memory/*.db (tools only)

--- GitNexus context --- /Users/monsieurbarti/Projects/The-Forge-Flow/hippo-memory-pi/src/skills/hippo-memory/SKILL.md: { "processes": [], "process_symbols": [], "definitions": [ { "id": "Section:README.md:L25:What it does", "name": "What it does", "filePath": "README.md", "startLine": 25, "endLine": 30 }, { "id": "Section:README.md:L31:Features", "name": "Features", "filePath": "README.md", "startLine": 31, "endLine": 38 }, { "id": "File:README.md", "name": "README.md", "filePath": "README.md" }, { "id": "File:package.json", "name": "package.json", "filePath": "package.json" } ] }