# hippocampus-memory-system

**Repository Path**: cloudside/hippocampus-memory-system

## Basic Information

- **Project Name**: hippocampus-memory-system
- **Description**: OpenClaw 海马体记忆压缩系统插件
- **Primary Language**: Unknown
- **License**: EPL-1.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧠 Hippocampus Memory System 2.0

> From "a forgetful assistant" to "a reliable colleague" — eventually becoming a **trusted old friend**.

Hippocampus is a persistent memory system for AI assistants. It transforms AI from something that "forgets after long conversations" into something that "never loses what matters" — by engraving key decisions, user preferences, and project context into persistent storage with semantic indexing and instant retrieval.

---

## What You Get with Hippocampus 2.0

### 1. Compression-Resistant Memory — "Written in Sand" vs "Carved in Stone"

**Without Hippocampus:**
> After 20 turns of conversation, the AI asks: "What budget system? I have no memory of that."

LLM context windows are finite. The longer the conversation, the more aggressively earlier content gets compressed. Decisions made three days ago, interface specs confirmed last week, constraints emphasized yesterday — all vanish like words written in sand.

**With Hippocampus 2.0:**
> "The budget alert threshold is 10% monthly overage — yellow warning. You set that on May 10th."

625 memories carved into persistent storage with semantic indexing. Search for "budget alert" after 50 conversation turns, and that decision from three days ago comes back instantly. The tide can't wash it away.

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **Retention** | Relies on OpenClaw compression; lost in long conversations | Permanent storage + HNSW index; 625 memories instantly retrievable |
| **Cross-day sessions** | New session = blank slate | Auto-retrieves history; continuous context |

---

### 2. Semantic Recall — "Exact Words" vs "What You Meant"

**Without Hippocampus:**
> Search for "approval workflow" → system only finds paragraphs containing the exact words "approval" and "workflow".

Keyword matching. Change your phrasing and it goes blind. Say "sign-off rules" instead of "approval workflow" — blind. Say "scheduler bug" instead of "scheduler failure" — even more blind.

**With Hippocampus 2.0:**
> Ask "what was wrong with the scheduler last time?" → retrieves: "scheduler 36-hour outage investigation: background thread never started..."

Semantic retrieval + project encoding + query expansion, fused in three layers. Say "scheduler" and it finds "scheduler". Say "scheduler" and it finds the Chinese equivalent too. Even a lone English abbreviation gets automatically expanded into a combined "query + project" search and still retrieves results.

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **Search Method** | Keyword grep | Semantic vectors + project association + query expansion |
| **Paraphrasing** | Not found | Still recalled |
| **English terms** | Zero recall | Auto-expanded and retrieved |

---

### 3. No More Repeating Yourself — "Let me explain again" vs "I remember"

**Without Hippocampus:**
> Every new session starts with: "I prefer direct, to-the-point responses. No emojis. Point out problems directly."

User preferences, constraints, design principles — all need to be re-stated every session. After 10 repetitions, even you get tired of it.

**With Hippocampus 2.0:**
> In the first second of a new session, the AI already knows: "honest and direct > people-pleasing", "sharp judgment beats flawlessly correct blandness", "no emojis".

These aren't sitting in a file waiting for you to dig them up. They're automatically retrieved and injected into context before every conversation.

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **User Preferences** | Stored in files; AI never actively uses | Auto-retrieved and injected before every conversation |
| **Repetition** | Re-stated every new session | One capture, remembered forever |

---

### 4. Project Context Aggregation — "Scattered Fragments" vs "Battlefield Map"

**Without Hippocampus:**
> Union finance system requirements, voucher approval bugs, budget alert rules — scattered across `memory/2026-05-08.md`, `memory/2026-05-10.md`, `MEMORY.md`.

Want to review "all decisions made on the union finance system so far"? Manually open three or four files and scroll through them. No global view.

**With Hippocampus 2.0:**
> Search "union finance system" → auto-recalls 5 related memories + 14 project summaries.

The system automatically aggregates memories under the same project: requirement confirmation, technology selection, bug fixes, user permission design — arranged in a timeline, with type distribution visible at a glance. Each project auto-generates a summary, as clear as a battlefield map.

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **Project View** | None; fragments scattered across files | Auto-aggregation + project summaries |
| **Global Review** | Manual file browsing | One search, full panorama |

---

### 5. Cross-Session Persistence — "What you said yesterday" vs "What you said three days ago"

**Without Hippocampus:**
> "That plan I mentioned yesterday..." → "Sorry, I don't remember what we talked about yesterday."

Every session is an island. Yesterday's discussion, the requirements confirmed the day before — all blank in a new session.

**With Hippocampus 2.0:**
> "What was the representative ratio in the last union transition plan?" → instantly recalls the May 12th record.

Session association recall: not only remembers the content, but also which memories belong to the same conversation. When you ask "last time", it automatically brings in all related memories from the same session.

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **Session Isolation** | Completely isolated | Session-linked, cross-session recall |
| **"Last time"** | AI doesn't know which time | Auto-identifies same-session context |

---

### 6. Auto-Organization — "Messy Notes" vs "Auto-Archived Filing Room"

**Without Hippocampus:**
> 15 markdown files in `memory/` directory, growing larger. No summaries, no classification, no cleanup.

303 memories = 303 pieces of unstructured text. Want to review a topic? Scroll from top to bottom.

**With Hippocampus 2.0:**
> Dreaming mechanism automatically clusters orphan memories daily, generates project summaries weekly, and cleans up expired content.

625 memories organized into 14 project summaries across 8 hierarchical levels. The system automatically tells you: "Union finance system has 5 related memories; latest progress is budget alert rules." No manual organization needed.

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **Memory Organization** | Pure chronological, unstructured | Project hierarchy + auto-summaries + Dreaming clusters |
| **Maintenance Cost** | Ever-increasing (files grow larger) | Auto-organized, fixed cost |

---

### 7. Emotional Awareness — "Flat Memory" vs "Warm Recollection"

**Without Hippocampus:**
> All memories treated equally. Failed lessons mixed with exciting breakthroughs.

**With Hippocampus 2.0:**
> Search "any recent breakthroughs?" → filter for positive memories (valence > 0.5), recall that exciting solution.
> Search "what pitfalls have we hit?" → filter for negative memories (valence < 0), recall the lesson learned.

Every memory carries an Arousal-Valence emotional coordinate. Retrieval isn't just "find relevant content" — it's also "find positive/negative memories", "find calm daily records", "find exciting breakthrough moments".

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **Emotional Dimension** | None | Arousal-Valence continuous coordinates |
| **Search Granularity** | Content matching only | Content + emotion + project + time |

---

### 8. Adaptive Retrieval — "Fixed Threshold" vs "Understanding Nuance"

**Without Hippocampus:**
> Ask "anything else?" → strict threshold returns only 1 item.
> Ask "just the most relevant" → loose threshold returns 10 noisy items.

**With Hippocampus 2.0:**
> "Anything else?" → auto-loosens threshold + expands top_k, gives more alternatives.
> "Just the most relevant" → tightens threshold + reduces top_k, only the essence.

The system understands your intent, not rigidly executing the same parameters.

| | Native Memory | Hippocampus 2.0 |
|---|---|---|
| **Retrieval Strategy** | Fixed parameters | Adaptive adjustment based on query intent |

---

## Quick Technical Comparison

| Dimension | 1.0 Basic | 2.0 Smart |
|-----------|-----------|-----------|
| Semantic Search | ✓ | ✓ HNSW O(logN) |
| Semantic Deduplication | ✗ | ✓ cos≥0.85 |
| Emotion Classification | ✗ | ✓ 5-class inference + **Arousal-Valence coordinates** |
| Project Inference | ✗ | ✓ 50 projects, hierarchy support |
| Project Summaries | ✗ | ✓ ≥3 memories trigger + 1h throttle |
| Dreaming | ✗ | ✓ Daily + Weekly auto-maintenance |
| Session Association | ✗ | ✓ 30-min sliding window |
| Query Expansion | ✗ | ✓ Isolated-term auto-expansion |
| Native Sync | ✗ | ✓ Watchdog file monitoring |
| Health Observability | ✗ | ✓ /health + /metrics + /stats |

**Overall Rating: A-** (Core Retrieval A+ / Write A / Structural Richness B+)

---

## Quick Start

### Requirements

- Python 3.10+
- Dependencies: `fastapi`, `uvicorn`, `aiosqlite`, `hnswlib`, `numpy`, `httpx`, `structlog`, `sentence-transformers`, `watchdog`
- Embedding model: `BAAI/bge-small-zh-v1.5` (auto-downloaded on first run)

### One-Command Deploy

```bash
curl -fsSL https://gitee.com/cloudside/hippocampus-memory-system/raw/main/deploy.sh | bash
```

Or manually:

```bash
git clone https://gitee.com/cloudside/hippocampus-memory-system.git
cd hippocampus-memory-system
pip install -r requirements.txt
python -m hippocampus.main
```

The daemon starts at `http://127.0.0.1:9527` by default.

### Verify Installation

```bash
curl http://127.0.0.1:9527/health
curl http://127.0.0.1:9527/stats
```

---

## Core API

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/capture` | POST | Capture memory (auto-dedup + inference) |
| `/search` | POST | Semantic search (vectors + project + summaries) |
| `/summaries` | GET | List project summaries |
| `/summaries/generate` | POST | Manually refresh summaries |
| `/dreaming/trigger` | POST | Manually trigger Dreaming |
| `/dreaming/status` | GET | Dreaming health status |
| `/feedback` | POST | Feedback to reinforce memory weight |
| `/health` | GET | System health check |
| `/stats` | GET | Memory statistics |
| `/metrics` | GET | Prometheus metrics |

Full endpoint documentation: [API.md](docs/API.md)

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw Agent Core                       │
│         (calls hippocampus_search / capture tools)          │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼──────────────────────────────┐
│              Hippocampus Daemon (FastAPI)              │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   Buffer    │  │  Scheduler   │  │   Dreaming   │  │
│  │  (Hot Mem)  │  │(Consolidate) │  │(Auto-Maint)  │  │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                │                  │         │
│  ┌──────▼────────────────▼──────────────────▼──────┐  │
│  │              Unified Storage Layer              │  │
│  │  ┌──────────────┐  ┌──────────────────────┐  │  │
│  │  │   Metadata   │  │     Vector Store     │  │  │
│  │  │   (SQLite)   │  │    (HNSW Index)      │  │  │
│  │  └──────────────┘  └──────────────────────┘  │  │
│  └────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## System Status (Production)

| Metric | Value |
|--------|-------|
| Total Memories | 626 |
| HNSW Index | 626/626 (100%) |
| Emotion Coordinates | 100% coverage |
| Project Coverage | 78.2% |
| Scheduler | Running, 0 pending |
| Avg Retrieval Latency | ~87ms |

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

---

## Documentation

- [需求规格说明书](docs/REQUIREMENTS.md) — 功能需求、API 清单、数据模型、配置说明
- [架构设计文档](docs/DESIGN.md) — 架构图、组件详解、数据流、设计决策
- [API 详细文档](docs/API.md) — 端点定义、请求/响应模型、调用示例

> Note: 文档版本与代码仓库同步维护。

---

## License

MIT