afx-hippocampus 0.1.0

Neuroscience-inspired memory framework for AI agents / 海马体 — Agent 大脑记忆框架

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?

Feature	Mem0	Letta	Zep	Hippocampus
Memory consolidation	-	-	-	Automatic
Forgetting / decay	-	-	Implicit	Dynamic TTL formula
Tag-based knowledge graph	-	-	Partial	Built-in
Zero-config deployment	-	-	-	SQLite, one command
Vector search optional	-	-	-	Progressive disclosure
Multi-model (OpenAI/Claude/Qwen/GLM/Kimi)	Partial	Partial	Partial	Via LiteLLM

Architecture

API / MCP / CLI
▼
HIPPOCAMPUS Working Memory Inbox
▼  Consolidation Agent (Agentic RAG · Classify · Conflict Resolve · Tag Extract)
SEMANTIC Facts & Knowledge	EPISODIC Events & History	PREFERENCE Likes & Dislikes	PROCEDURAL Skills & How-to	CUSTOM Your Partitions
▼  Hybrid Retrieval  ⟷  Knowledge Graph  ⟷  Forgetting (Dynamic TTL)

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.

Alternative install methods

Docker:

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

One-line install:

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

Try it in 30 seconds

# 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:

Stage	What Happens	Trigger
Ingest	New memories land in the working memory inbox (mem_hippocampus)	API write
Consolidate	Agent classifies into partition, resolves conflicts, extracts tags → Knowledge Graph	Periodic / manual
Retrieve	Three-path hybrid search (vector + keyword + graph) with recency/importance/relevance scoring	API search
Forget	Dynamic TTL: base × (1 + log(access)) × importance × exp(-decay × days) — frequently used memories survive, neglected ones fade	Periodic

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

Field	Default	Description
llm_model	openai/gpt-4o-mini	LLM model identifier (via LiteLLM)
llm_api_key	null	LLM provider API key (required for consolidation)
llm_base_url	null	Custom LLM API endpoint (for Qwen/GLM/Kimi)
storage_type	sqlite	sqlite or postgresql
embedding_enabled	true	Set false to disable vector search
port	8321	Server port
consolidation_interval_seconds	3600	How often consolidation runs
base_ttl_hours	168	Base memory TTL before decay

Storage backends

SQLite (default) — zero-config, single file, great for personal use and development.

PostgreSQL + pgvector — production-grade, connection pooling, native vector types.

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:

Provider	Model Example	Env Var
OpenAI	openai/gpt-4o-mini	OPENAI_API_KEY
Anthropic	anthropic/claude-3-haiku-20240307	ANTHROPIC_API_KEY
Qwen (Alibaba)	openai/qwen-plus	HIPPOCAMPUS_LLM_API_KEY + HIPPOCAMPUS_LLM_BASE_URL
GLM (Zhipu)	openai/glm-4	HIPPOCAMPUS_LLM_API_KEY + HIPPOCAMPUS_LLM_BASE_URL
Kimi (Moonshot)	openai/moonshot-v1-8k	HIPPOCAMPUS_LLM_API_KEY + HIPPOCAMPUS_LLM_BASE_URL

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