afx-hippocampus

Hippocampus 海马体

Neuroscience-inspired memory framework for AI agents

English | 中文

Hippocampus gives your AI agents a brain-like memory system. Just like the human hippocampus consolidates short-term experiences into long-term knowledge, this framework automatically organizes, prioritizes, and forgets memories so your agents stay sharp.

Why Hippocampus?

Architecture

Quick Start

pip install afx-hippocampus      # Install
hippocampus init                  # Initialize (creates hippocampus.json + SQLite DB)
hippocampus config set llm_api_key sk-your-key-here  # Set LLM key
hippocampus start                 # Start server → http://localhost:8321/

Open http://localhost:8321/ for the Web Console, or http://localhost:8321/docs for the API docs.

git clone https://github.com/afx-team/hippocampus.git && cd hippocampus
docker compose -f docker/docker-compose.yml up

curl -fsSL https://raw.githubusercontent.com/afx-team/hippocampus/main/scripts/install.sh | sh

# Store a memory
curl -X POST http://localhost:8321/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode", "tags": ["preference", "ui"], "importance_score": 7.5}'

# Search memories
curl -X POST http://localhost:8321/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "UI preferences", "top_k": 5}'

# Trigger consolidation manually
curl -X POST http://localhost:8321/api/v1/admin/consolidate

# Explore the knowledge graph
curl http://localhost:8321/api/v1/graph/tags
curl http://localhost:8321/api/v1/graph/neighbors/python?depth=2

How It Works

Memories flow through four stages — inspired by how the human hippocampus consolidates short-term experiences into long-term knowledge:

Full details: Memory Lifecycle · Consolidation · Hybrid Search · Forgetting

Configuration

All config lives in hippocampus.json — no environment variables needed.

hippocampus config list                    # View all settings
hippocampus config set llm_model openai/gpt-4o  # Change model
hippocampus config set llm_base_url https://dashscope.aliyuncs.com/compatible-mode/v1  # Qwen/GLM/Kimi

pip install afx-hippocampus[pg]
hippocampus config set storage_type postgresql
hippocampus config set pg_url postgresql://user:pass@localhost/hippocampus

Full config reference: Configuration Guide

Supported Models

Via LiteLLM, Hippocampus works with any major LLM provider:

Development

git clone https://github.com/afx-team/hippocampus.git
cd hippocampus
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/

# Type check
mypy src/hippocampus/

See CONTRIBUTING.md for contribution guidelines.

Roadmap

• Core memory model with 5 brain-inspired partitions
• SQLite + sqlite-vec storage backend
• PostgreSQL + pgvector storage backend
• Memory consolidation agent (Agentic RAG)
• Dynamic forgetting with exponential decay
• Tag-based knowledge graph
• FastAPI REST API
• CLI tooling + Docker deployment
• Built-in Web Console (memory CRUD, search, graph visualization)
• Evaluation benchmarks (LoCoMo, LongMemEval, ConvoMem, PersonaMem)
• MCP server for Claude Code / OpenClaw integration
• Multi-agent shared memory
• Emotional tagging and memory importance learning

Research

This project draws on research from:

• Generative Agents — recency-importance-relevance retrieval
• MemGPT / Letta — agent-driven memory management
• CoALA — episodic/semantic/procedural taxonomy
• Zep / Graphiti — temporal knowledge graphs

See repo_pages/papers/ for detailed survey notes.

License

Apache License 2.0

Built by afx-team