Metadata-Version: 2.4
Name: echomind-memory
Version: 1.1.5
Summary: 四层认知记忆系统 for AI agents — 世界事实 / 经历 / 观察 / 心智模型，LLM 反射引擎自动提炼
Author: xiangjianhuan007
License: MIT
Project-URL: Homepage, https://github.com/xiangjianhuan007/echomind-memory-cn
Project-URL: Repository, https://github.com/xiangjianhuan007/echomind-memory-cn
Project-URL: Issues, https://github.com/xiangjianhuan007/echomind-memory-cn/issues
Keywords: ai,memory,llm,agent,rag,cognitive,hermes
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.28
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

[![OpenClaw Compatible](https://img.shields.io/badge/OpenClaw-Compatible-brightgreen)](https://github.com/OpenClaw)
[![Hermes-Agent Ready](https://img.shields.io/badge/Hermes--Agent-Ready-blue)](https://github.com/Hermes-Agent)
[![Claude Code Supported](https://img.shields.io/badge/Claude%20Code-Supported-orange)](https://claude.ai/code)
[![OpenCode Compatible](https://img.shields.io/badge/OpenCode-Compatible-red)](https://github.com/open-code-ai)

# EchoMind v2.0 — Chinese Enhanced Edition

🌐 **中文版:** [README.zh-CN.md](README.zh-CN.md)

> A cognitive architecture-level fork of [echomind_memory.skill](https://github.com/jasonatgit/echomind_memory.skill) (official v1.1.5).
> Borrowing Hindsight's "soul" and wrapping it in EchoMind's "shell." Your AI doesn't just "remember" anymore — it **thinks**.

---

## 🧠 Four-Layer Cognitive Architecture (Crushes Traditional Vector Search)

Most memory systems do only one thing: **store in, search out**. Like a goldfish — it knows you talked yesterday, but has no idea why, what conclusions were reached, or what to do next time.

**EchoMind v2.0 borrows Hindsight's cognitive science architecture, upgrading memory from a "hard drive" to a "brain":**

| Layer | Human Analogy | What It Does |
|:---|:---|:---|
| **🌍 World Facts** | "Fire is hot" | Categorize objective knowledge, trace sources |
| **📝 Experience** | "I touched that bright thing and got burned" | Full context + outcome for every interaction |
| **🔍 Observation** | "That bright thing is hot, might be fire" | **Auto-extract patterns from conversations** |
| **🧠 Mental Model** | "Don't touch bright things" | Confirmed observations → **auto-write to system preferences** |

This isn't fancy categorization. This is a fundamental leap from "storage" to "cognition."

## ⚡ Three Core Upgrades

### 1. Reflection Engine: From "Dead" to "Alive"

The original reflection engine never fired (the code literally said "don't reflect when LLM is available" — like buying a supercomputer and using it as a calculator).

**v2.0 fix**: Three-tier degradation strategy, LLM-driven semantic analysis, auto-triggers a brain review every 8 conversations.

### 2. Observation Layer: From "Single Record" to "Pattern Discovery"

New `observation_memory` table, auto-deduplication, confidence accumulation:

```
1st occurrence → "User prefers concise replies" (conf=0.5, hit=1)
2nd occurrence → "Same pattern again" (conf=0.65, hit=2)
3rd occurrence → "Confirmed" (conf=0.75, hit=3) → **promoted to mental model**
```

### 3. Mental Model Auto-Sedimentation

When a pattern appears **3 times** with confidence **≥0.6**, auto-write to MEMORY.md/USER.md — permanently.

## 🆚 Comparison

| Dimension | Original EchoMind | EchoMind v2.0 | Hindsight |
|:---|:---:|:---:|:---:|
| Storage | 9 flat tables | 11 tables + 4-layer | Cloud PostgreSQL |
| Reflection Engine | ❌ Never fires | ✅ LLM 3-tier | ✅ Built-in |
| Pattern Discovery | ❌ None | ✅ observation_memory | ✅ Automatic |
| Mental Models | ❌ None | ✅ Auto-write to files | ✅ Cloud storage |
| Offline | ✅ | ✅ | ❌ API-dependent |
| Deploy Cost | Zero | Zero | ~1GB Docker |

## 📦 Usage

```yaml
# config.yaml
memory:
  provider: echomind
  enabled: true
```

No extra deployment, no Docker, no API key. Change one config line, restart, done.

## 🔧 Files Modified (615 lines added)

| File | Change |
|:---|:---|
| `core/_reflective_fallback.py` | 200-line shell → 400-line complete reflection engine |
| `core/storage/sqlite_store.py` | New observation table + source_type migration |
| `adapters/hermes_provider.py` | Reflection loop + mental model auto-sedimentation |

## 🔗 Links

- Official: https://github.com/jasonatgit/echomind_memory.skill
- Chinese Enhanced: https://github.com/xianjianhuang/echomind-memory-cn

---

*This isn't a plugin. This is an AI Multi-Agent Memory Neural Network with self-reflective memory.*
