Back to packageRELEASE DETAILS

0.1.0

PyPI

afx-hippocampus

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

Published20 Apr 2026

Direct dependencies25

Transitive dependenciesNot calculated

README

Version 0.1.0 documentation

Hippocampus 海马体

Neuroscience-inspired memory framework for AI agents

English | 中文

Python

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

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

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 25

Native requirements

25 direct targetsNot calculated transitive count

Package / target	Requirement	Relationship
fastapi Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`fastapi>=0.115.0`	runtime
uvicorn Environment { "extras": "standard", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`uvicorn[standard]>=0.30.0`	runtime
litellm Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`litellm>=1.40.0`	runtime
pydantic Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pydantic>=2.0.0`	runtime
sqlite-vec Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`sqlite-vec>=0.1.0`	runtime
aiosqlite Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`aiosqlite>=0.20.0`	runtime
numpy Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`numpy>=1.24.0`	runtime
sentence-transformers Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`sentence-transformers>=3.0.0`	runtime
apscheduler Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`apscheduler>=3.10.0`	runtime
click Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`click>=8.0.0`	runtime
rich Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`rich>=13.0.0`	runtime
httpx Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`httpx>=0.27.0`	runtime
PyJWT Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`PyJWT>=2.8.0`	runtime
networkx Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`networkx>=3.1`	runtime
mcp Environment { "extras": "", "marker": null, "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`mcp>=1.0.0`	runtime
asyncpg Environment { "extras": "", "marker": "extra == \"pg\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`asyncpg>=0.29.0; extra == "pg"`	runtime
pgvector Environment { "extras": "", "marker": "extra == \"pg\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pgvector>=0.3.0; extra == "pg"`	runtime
pytest Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pytest>=8.0.0; extra == "dev"`	runtime
pytest-asyncio Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pytest-asyncio>=0.23.0; extra == "dev"`	runtime
pytest-cov Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pytest-cov>=5.0.0; extra == "dev"`	runtime
ruff Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`ruff>=0.5.0; extra == "dev"`	runtime
mypy Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`mypy>=1.10.0; extra == "dev"`	runtime
datasets Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`datasets>=2.0.0; extra == "dev"`	runtime
pandas Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`pandas>=2.0.0; extra == "dev"`	runtime
scikit-learn Environment { "extras": "", "marker": "extra == \"dev\"", "requires_python": ">=3.10", "evaluation": "NOT_EVALUATED" }	`scikit-learn>=1.3.0; extra == "dev"`	runtime