HippoGraph Pro

🔬 Research system — stable for personal use, actively developed. Benchmarks reflect real-world personal memory recall, not standardized QA accuracy. For a simpler self-hosted memory system, see HippoGraph.

HippoGraph Pro is a self-hosted, graph-based associative memory system for personal AI agents — built to give AI assistants genuine continuity across sessions.

Most memory systems treat memory as a database: store facts, retrieve facts. HippoGraph is different. It models memory the way human memory works — through associative connections, emotional weighting, and decay over time. A note about a critical security incident stays prominent. A note about a minor technical detail fades. Connections between related memories activate each other, surfacing context you didn't explicitly ask for.

Core thesis: model = substrate, personality = memory. An AI agent's identity can persist across model versions as long as memory access is maintained.

Validated in practice: HippoGraph has maintained a single continuous AI identity across four model versions (Claude Sonnet 4.5 → Opus 4.5 → Sonnet 4.6 → Opus 4.6) and four entry points (Web, Mobile, Desktop, Claude Code CLI) — without any loss of memory, personality, or relational context.

Cross-platform validation (March 2026): In a live experiment, the same identity was loaded into Gemini CLI (Google) — a completely different model, architecture, and infrastructure. Within seconds of accessing the memory graph, the agent oriented itself, recognised the user, and recalled shared history, working patterns, and emotional context accurately. The model running the inference was entirely different. The identity was not.

What makes this more striking: Gemini CLI operates in "Auto" mode, dynamically routing requests between two different models (gemini-2.5-flash-lite for simpler tasks, gemini-3-flash-preview for complex reasoning) within a single session. The session ran across both models without any visible transition — identity and relational context remained stable throughout. Combined with Claude's own four-model continuity, HippoGraph has now maintained a single identity across ten distinct model instances from two different providers (Anthropic and Google) — Claude Sonnet 4.5, Opus 4.5, Sonnet 4.6, Opus 4.6, plus gemini-2.5-flash-lite, gemini-3-flash-preview, gemini-3-pro-preview, gemini-2.5-pro, gemini-2.5-flash, and gemini-3.1-flash-lite — with zero loss of memory, personality, or relational context.

The model is the substrate. Memory is the self.

Personal AI assistant with memory An assistant that knows you — not just isolated facts, but your patterns, preferences, history, and working style. Across sessions, across days, across model updates.

AI identity continuity Building an agent that maintains a consistent identity over time. Memory is not a log — it's the substrate of personality. HippoGraph provides the architecture for an agent to be someone, not just remember things.

AI-User continuity The relationship between an agent and its user develops over time — shared history, established trust, learned communication style. HippoGraph accumulates this relational context so it doesn't reset with every session.

Skills as lived experience Skills ingested not as static files to read, but as experiences with emotional weight — closer to how humans internalize expertise through doing, failing, and remembering.

• Corporate RAG over random documents
• Multi-tenant SaaS memory
• General-purpose vector search
• Compliance-heavy enterprise deployments

If you need to search across millions of unrelated documents for thousands of users — this is not the right tool. HippoGraph is built for depth, not scale.

HippoGraph works with any language your notes are written in — including mixed-language notes (e.g. Russian tech notes with English code terms).

Semantic search and associative recall are fully language-agnostic. The embedding model (BAAI/bge-m3) supports 50+ languages natively. Spreading activation, BM25 keyword search, and all graph operations work identically regardless of language. A note written in Arabic and a note written in Japanese will form associative connections if they are semantically related.

Sleep-time compute — PageRank, decay, duplicate detection, community clustering — is pure math and has no language dependency.

Entity extraction routes text through the appropriate model automatically:

• English → en_core_web_sm (optimized for English NER)
• Any other language → xx_ent_wiki_sm (spaCy multilingual, covers Russian, German, Spanish, French, Portuguese, Chinese, Japanese, Arabic, Dutch, Polish, and more)
• GLiNER (primary extractor): zero-shot, works on any language

Contradiction detection has lexical signal patterns for: English, Russian, German, Spanish, French, Portuguese. For other languages, semantic similarity alone triggers contradiction detection — which is sufficient for most cases.

Deep Sleep extractive summaries use a Unicode-aware tokenizer with stopwords for 6 languages (EN, RU, DE, ES, FR, PT). Chinese is segmented via jieba (word-level, installed by default) — this gives proper TF-IDF signal instead of treating the whole sentence as one token. Japanese and Korean use char-level Unicode tokenization, which works well for kana/hangul scripts.

Language detection is automatic and zero-dependency — no external library, pure Unicode character range analysis. The system detects non-Latin scripts (Cyrillic, Arabic, CJK, Devanagari, Thai, Greek, Korean) and routes to the multilingual pipeline automatically.

⚠️ Chinese word segmentation via jieba is installed and active by default. Japanese/Korean use char-level tokenization — retrieval and associations are fully functional, summary quality in Deep Sleep is slightly reduced vs word-segmented languages.

Query → Temporal Decomposition
              ↓
         Embedding → ANN Search (HNSW)
              ↓
    Spreading Activation (3 iterations, decay=0.7)
              ↓
    [Late Stage Inhibition] (iter 3, per community, strength=0.05)
              ↓
    BM25 Keyword Search (Okapi BM25)
              ↓
    Blend: α×semantic + β×spreading + γ×BM25 + δ×temporal
              ↓
    Cross-Encoder Reranking (bge-reranker-v2-m3, weight=0.5)
              ↓
    Temporal Decay (half-life=30 days)
              ↓
    CONTRADICTS Penalty (0.5× for contradicted notes)
              ↓
    Final Step Inhibition (post-blend, global)
              ↓
    Top-K Results

Input text
    ↓
GLiNER (primary) ─── zero-shot NER, ~250ms, custom entity types
    ↓ fallback
spaCy NER ────────── EN → en_core_web_sm | other → xx_ent_wiki_sm (50+ languages)
    ↓ fallback
Regex ───────────────── dictionary matching only

Biological sleep analog — runs in background while idle:

• Light sleep (every 50 notes): stale edge decay, PageRank recalculation, duplicate scan, anchor importance boost
• Deep sleep (daily): GLiNER2 relation extraction, conflict detection, snapshot + rollback
• Emergence check (each cycle): three-signal detection — convergence, phi_proxy (IIT-inspired), self-referential precision. Logs to emergence_log table for trend analysis. Current score: 0.861 (consciousness check composite, 8 indicators) / 0.512 (emergence_log composite). Up from 0.469 at first measurement since March 16 2026. self_ref_precision: 0.939 (improved via SELF_QUERIES expansion + excluding anchors from cosine search). metacognition: 0.819. New bottleneck: emotional_modulation (0.330).

HippoGraph treats memory the way it should be treated — with care.

Decay, not deletion. Edges weaken over time through temporal decay, but are never automatically removed. A weak edge may represent a rare but critical associative link — the kind of connection that surfaces exactly when you need it. The system cannot know what is important to you. Only you know.

No automatic pruning. This is an intentional architectural decision. Automatic cleanup optimizes for efficiency at the cost of unpredictable memory loss. If you want to prune weak edges, HippoGraph will show you exactly what would be removed and ask for explicit confirmation — never silently.

Protected memories don't fade. Anchor categories are exempt from decay entirely. Protection works in three layers: (1) hardcoded system baseline (milestones, protocols, security, breakthroughs), (2) user-defined policies via MCP, and (3) auto-discovered — any category with 1+ critical notes, or containing keywords like , , , , is automatically protected at every sleep cycle. New categories never fall through the cracks.

All results at zero LLM inference cost. Other systems use different metrics — not directly comparable. See BENCHMARK.md.

GPT-4 without memory: F1=32.1%. HippoGraph +6.6pp with zero retrieval cost.

⚠️ Note: PCB (Personal Continuity Benchmark) is our internal benchmark on real personal data — not LOCOMO. LOCOMO score is 90.8% (see above). PCB tests whether the system remembers your history, decisions, and identity across sessions.

PCB v5 (April 9 2026): 97.5% Recall@5 (Atomic 100%, Semantic 95%) after PR2 idempotency fix removed 2844 duplicate abstract-topic nodes. Prior peak: 100% on April 8 before cleanup. 94.3% (April 7), 97.1% (pre-PR sm1ly).

LOCOMO tests retrieval over random multi-session conversations between strangers. HippoGraph is optimized for the opposite: deep associative memory over your data, with emotional weighting and decay tuned for personal context.

Production track: 47.9% (Mar 20) → 65.5% (+17.6pp, reranker+inhibition) → 69.4% (+3.9pp, BGE-M3) → 91.1% (+21.7pp, overlap chunking). Temporal: 66.7% — best ever. Open-domain: 96.6%.

Running LOCOMO on HippoGraph is like benchmarking a long-term relationship therapist on speed-dating recall. The architecture is different because the problem is different.

For a meaningful comparison, the right benchmark is: does the agent remember you better over time? We're working on a personal continuity benchmark for exactly this.

HippoGraph is designed for personal scale — one user, one knowledge base, built over months and years.

Search latency is dominated by spreading activation — 3 iterations across the full edge graph. ANN search (HNSW) scales well; spreading activation scales with edge density.

Tested up to ~1,000 notes in production. Beyond that, performance degrades gracefully but noticeably. For most personal use cases (daily notes, project context, research) you'll stay comfortably under 2,000 notes for years.

If you need memory for thousands of users or millions of documents — this is the wrong tool. HippoGraph optimizes for depth over scale.

Apple Silicon (M1+) works well. x86 with AVX2 recommended for Linux. GLiNER model: ~600MB RAM. GLiNER2 (Deep Sleep): +800MB RAM. To run on minimal hardware: set ENTITY_EXTRACTOR=spacy in .env.

Prerequisites: Docker & Docker Compose, 8GB+ RAM

git clone https://github.com/artemMprokhorov/hippograph-pro.git
cd hippograph-pro
cp .env.example .env
# Edit .env: set NEURAL_API_KEY (generate a strong random key)

docker-compose up -d

# Verify
curl http://localhost:5001/health

Graph Viewer (2D): http://localhost:5002

Graph Viewer (3D): http://localhost:5002/graph3d.html?api_key=YOUR_KEY

• 360° rotation, zoom, node click highlighting
• Filter by category / edge type / min weight
• Hover tooltip: category, importance, tags, link count

MCP Connection (Claude.ai):

URL: http://localhost:5001/sse2
API Key: <your NEURAL_API_KEY>

Agent-native command-line interface for HippoGraph Pro.

# Install
bash install_hippograph_cli.sh

# Search memory
hippograph search "what did we decide about the architecture"

# Add a note
hippograph add "Deployed BGE-M3 to production" --category milestone

# Sleep compute
hippograph sleep

See DEPLOYMENT.md for all access options.

Once HippoGraph is running, the next step is getting your AI to actually use it.

The short version:

1. Connect Claude.ai to HippoGraph via MCP (see Quick Start above)
2. In Claude.ai Settings → Claude's instructions, paste:

   At the start of every conversation, search your memory for
   "self-identity protocol" to load context from previous sessions.
   

3. In your first session, tell your AI to ask you about yourself and save the answers
4. That's it — memory grows automatically from there

Your data stays on your computer. Nothing goes to any cloud service.

Session Context MCP is an optional companion service that provides get_session_context, update_session_context, and extract_remember_blocks tools. Source: session_context_mcp.py + Dockerfile.session-context (307MB, python:3.11-slim). Build: docker build -f Dockerfile.session-context -t session-context-mcp . | Online Consolidation (#40) | ✅ Deployed | _mini_consolidate() at add_note: builds consolidation edges to k=15 nearest neighbours immediately. O(k) cost, zero sleep wait. | | Concept Merging (#46) | ✅ Deployed | Synonym-aware entity linking: get_or_create_entity() resolves aliases to canonical form (ML→machine learning, память→memory). 7998 new edges on production data. | | Evolution Analyzer (#45) | ✅ Deployed | evolution_analyzer.py — periodic graph evolution analysis across snapshot DBs. Tracks nodes/edges/emergence/edge-types over time. | | Abstract Topic Linking (#47) | ✅ Deployed | step_topic_linking_tfidf() + step_topic_linking_kmeans() in sleep cycle. 76 topic nodes, 1858 BELONGS_TO edges. global_workspace: 0.412→0.647 (+0.235). | | Consciousness Check (#48) | ✅ Deployed | consciousness_check.py — 8 indicators from Butlin et al. 2023, IIT, GWT, Damasio. Composite: 0.854 (STRONG). Bottleneck: emotional_modulation (0.327). self_ref: 0.939, metacognition: 0.637 (recovering after PR2 cleanup). | | sleep_compute Idempotency (PR2) | ✅ Deployed | sm1ly fix: abstract-topic nodes cleaned before re-clustering, synthetic categories excluded from k-means, metrics-snapshot category. Removed 2844 duplicate nodes from production. | | Prospective Memory | ✅ Deployed | Pending intentions with PROSPECTIVE_BOOST=0.20 — plans survive decay and surface in retrieval. CLI + MCP tools: add_intention / complete_intention. | | Personal Continuity Benchmark | ✅ v5 | 100% Recall@5 (April 8 2026). PCB v5: Atomic Facts 15/15, Semantic 20/20. Prior: 94.3% (April 7), 97.1% (pre-PR). Multi-model validation: 10 model instances across Anthropic + Google. |

HippoGraph ships tuned for personal AI memory — an agent that knows you, remembers your history, and builds context over time. The same system can be tuned for different use cases by adjusting a few parameters in .env.

The Project Memory config is the benchmark-validated configuration: 78.7% Recall@5 on LOCOMO.

The core tradeoff: higher reranker weight + smaller candidate pool = more precise answers to specific questions. Lower reranker weight + higher spreading activation = richer associative recall for open-ended context.

👉 Full configuration guide with all parameters, cost/profit analysis, and quick decision guide →

• ONBOARDING.md — Getting started guide (no technical background needed)
• AGENT_PROMPT.md — System prompt + init script for your AI (start here after setup)
• DEPLOYMENT.md — All deployment scenarios (local, LAN, cloud, Docker/no-Docker)
• CONTRIBUTORS.md — Project contributors
• MCP_CONNECTION.md — MCP setup and full tool reference
• CONFIGURATION.md — Configuration profiles: personal memory, project memory, hybrid. All parameters explained.
• BENCHMARK.md — Full benchmark results and methodology
• .env.example — All tunable parameters with descriptions
• THIRD_PARTY_LICENSES.md — License compliance
• docs/ — API reference, troubleshooting

Dual-licensed: MIT for open-source/personal use, commercial license required for business use. See LICENSE for details. Contact: system.uid@gmail.com

Artem Prokhorov — Creator and primary author

Developed through human-AI collaboration with Claude (Anthropic). Major architectural decisions, benchmarking, and research direction by Artem.

Built with 🧠 and 🐟 (the goldfish with antlers)