Content
List
For (DeepSeek/OpenAIaude, etc.) to memory + switchable personality** plug-in libraries., can be directly imported library or accessed as an Service.
## Positioning (Honest Description)
This is a **well-integrated self-use tool/reference not a product with exclusive capabilities.
Each component is a: RAG (LangChain), conflict detection (mem ADD/UPDATE has been
temporal graph (ZGraphiti), query expansionDE), trust decay (Hermes).
Its actual value is **integration quality** - after multiple enhancement layers are coordinated,
the evaluation 77%→:
| Configuration | OVERALL (hard-core evaluation, baseline difficulty 77%) |
|------|------|
| Bare RAG | 77% |
| Naive all open (inter-layer interference) | 88% |
| all open (supers) | **96%> Note: 77→96 proves that "coordin layer > naive R but this is integration tuning new primitives -
> gets the same components can **For a single, use mem0/Z is more cost-effective.**
[docs/EVALUATIONdocs/EVALUATION.md) (including functional grading and fals) for details.
## Design (based on actual measurement and```
User Message
① RAG index recall trust plus weight reordering (FAISS + BGE, scalable)
-k all disclose into context (retrieve-then-read)
③ Conflict detection: automatically discover and down-weight old memory when writing
④ Personality adapter small model generates style examples (option A, optional)
⑤ Assemble prompt = [personality example] + [disclosed fact] + [user message]
⑥ DeepSeek answer
⑦ Usage feedback: only reinforce trust if actually adopted
```
**Why choose this** (third-party comparison and actual measurement, DeepSeek as the referee):
- Facts: RAG 2.0 / disclosure 1.83 > parameterized small model 0.96 → use RAG + disclosure for facts
-: semantic vector 0.79 >> keyword-based Holog.00 (question and answer scene words do not overlap use FAISS + BGE
- Facts can be, and modified in real-time: vector operations are millisecondically isolated, no training required
- Personality: multiple, each personality physically isolated, switching = switching adapter, avoiding catastrophic forgetting
## Core Functionality
### Trust Layer ( Hermes)
Each memory has a trust score, allowing + commonly used + fresh" memories to float to the top, and old noise to naturally sink to the bottom.
```
Recall final score = semantic similarity + 1 × effective trust # (to prevent Matthew effect)
Effective trust = trust × 0.5^(days unused / half-life) # pinned does not decay
```
- **trust**: new memory defaults0.5
- **reinforcement**: memory is by DeepSeek → trust increases (usage feedback, not "recall and then reinforce")
-**: if not used for time → effective trust decreases over time
- **pinned decays, always ranked first **superseded**: old superseded by, ranked after all normal### Conflict Detection (automatic)
Automatically detect conflicts with existing memory, and handle it in:
| Situation | Handling |
|------|------|
conflict (sim≥0) + CONTRADICTION trust goes to| High similarity (sim.8) + UPDATE memory trust × 2 |
| Medium similarity.7-0. + CONTRADICTION | old memory trust × 0 |
| Medium similarity (7-0.8 | old memory trust × 0.5 |
ATIBLE (compatible) | no change |
MechanismGE semantic retrieval similar candidatesSeek performs NLI judgmentTRADICTION/UPDATE/COMPATIBLE).
### Usage Feedback Loop
Not "recall and then reinforce" - compare DeepSeek's answer with the semantic similarity of each retrieved memory:
- High similarity (>0.5) = adopted → trust increases
- Low similarity (<0.3) = ignored → trust slightly decreases
Let trust truly reflect "which memory contributes to the answer".
### Memory Health Monitoring
Periodically check memory degradation:
- **similarity distinguishability** (top-k std): low = memories are too similar to distinguish
- **superseded proportion**: high = outdated memory accumulation
- **low trust proportion**: high = too much garbage
- automatic alarm cleanup list if exceeding threshold
### Personality Memory Partitioning
Each personality maintains an independent memory partition to prevent "personality leakage":
- **shared layer**: core facts shared by all personalities (name/job/address)
- ****: independent preferences/contextual memories for each personality
-: shared + current persona merged, other personas invisible
- switching personality = switching visible memory partition
## Hierarchical Responsibilities
| Layer | What to manage | Add | Delete | Modify |
|----|--------|-----|-----|-----|
| Cold memory RAG | large facts | insert vector | delete re-embed one |
| pinned | high | pinned=true | delete |
| Trust layer | consolidation/forgetting | usage feedback reinforcement | decay and sink || Conflict detection | automatic detection when writing | superseded down-weight | gradient |
| Health monitoring | quality monitoring | check_health() | | alarm |
| Personality adapter | behavior style | adapter | delete directory | adapter |
| Personality isolation | write by persona partition | switch## Installation
```powershell
uv venv --python 12
.venv\activate
uv pipe .
# torch >=.6 required ( requirement)
```
##1: Python Librarypython
from memory_engine.engine import MemoryEngine
engEngine(store_dir="./mem", deepseek_key="sk-...")
# memory addition, deletion, and modification (automatic conflict detection when writing)
result =_fact("user is Wei") # {"id": 1, "": [], "resolved}
result = eng.add_fact("user is named Li Ming # {"id": 2, "conflicts": [old entry], "resolved": True}
eng.update_fact(1, text="user is named Zhang Wei, backend engineer")
eng.delete_fact(1)
# personality (optional, requires training)
eng.create_persona("blunt", [
{"user": "Should we add caching?", "response": "Test the bottleneck first. If there's no bottleneck, don't add it."},
], desc="direct and concise")
eng.switch_persona("blunt")
# conversation with memory + personality (automatic trust update)
r = eng.chat("What's my name?", top_k=3)
print(r["response"]) # response
print(r["feedback"]) # [{"id": 1, "adopted": True, "sim": 0.72}]
# health check
health = eng.check_health()
print(health["alerts"]) # ["outdated accumulation: 30% superseded"]
cleanup = eng.suggest_cleanup() # [{"id": 3, "reasons": ["superseded","low_trust"]}]
# trust feedback
eng.reinforce_fact(1) # manual reinforcement
```
### Personality Partition Usage
```from memory_engine.partitioned_memory import PartitionedMemory
pm = PartitionedMemory("./mem")
# shared facts (visible to all personalities)
pm.add("user is named Zhang Wei", shared=True)
# personality-specific memories
pm.switch_persona("formal")
pm.add("user does not like emojis") # only visible in formal
pm.switch_persona("casual")
pm.add("user likes emoticons and memes") # only visible in casual
# automatic isolation during retrieval
pm.switch_persona("formal")
pm.retrieve("communication style") # returns shared + formal memories only
```
## Usage 2: HTTP Service
```powershell
$env:DEEPSEEK_API_KEY = "sk-..."
python -m memory_engine.service --port 8900
# add --no-persona to only use memory layer (no small model loading, faster and more memory-efficient)
```
API (POST JSON):
| Route | Input | Output |
|------|------|------ `POST /chat` | `{message, top_k}` | `{response, used_memory, feedback, latency_ms}` |
| `POST /facts/add` | `{text, | `{id, conflicts, resolved}` |
| `POST /facts/delete` | `{id}` | `{ok}` |
| `POST /facts/update` | `{id, text, pinned}` | `{ok}` |
| `GET/list` | - | `{facts}` |
| `GET /health` | - | `{healthy, alerts,ust, ...}` |
| `POST /persona/create` | `{id, examples, desc}` | `{_s}` |
| `POST /persona/switch` | `{id}` (null=no personality) | `{ok}` |
| `POST /persona/delete` | `{id}` | `{ok}` |
| `GET /persona/list` | - | `{personas}` |
## Adjustable Parameters
`memory_engine/fact_store.py`:
| Parameter | Default | Meaning |
|------|------|------|
| `DEFAULT_TRUST` | 0.5 trust of new memory |
| `REINFORCE_GAIN` | 0.15 | trust increase per adoption |
| `DECAY_HALF_LIFE_DAYS` | 30 | days for trust to halve (0=disable decay) |
| `TRUST_MIN` | 0.05 | trust lower bound |
`memorylict_detector.py`:
| Parameter | Default | Meaning |
|------|------|------|
| `SIMILARITY_THRESHOLD` | 0.7 | threshold for conflict detection |
`memory_engine/usage_feedback.py`:
| Parameter | Default | Meaning |
|------|------|------|
| `ADOPTION_THRESHOLD` | 0.5 | similarity threshold for adoption |
| `IGNORE_THRESHOLD` | 0.3 | similarity threshold for ignoring |
| `IGNORE_PEN` | 0.03 | trust decrease for ignoring |
## Actual Measurement Data
### Stress Test (105 memories)
| Indicator | Result | Threshold |
|------|------|------ False positive rate (no conflict triggered) | **0%** (0/90) | <10% |
| Conflict detection rate (should be caught) | **73%** (11/15) | ≥60% |
| Compatible misjudgment | **0%** (0/10) | 0% |
| Health | healthy | - |
| Trust distribution | 92 normal (0.5) + 13 down-weighted (0.1-0.3) | reasonable |
### Functional Verification
| Test | Result |
|------|------|
| End-to-end memory (addition/deletion/modification + RAG + DeepSeek) | ✅ ~700ms |
| Conflict detection (hard conflict/soft update/compatible) | ✅ gradient down-weighting correct |
| Usage feedback (only reinforce if adopted) | ✅ |
| Health monitoring (degradation detection + alarm) | ✅ |
| Personality partitioning (isolation + sharing) | ✅ zero leakage Trust layer does no harm | ✅ does not harm basic retrieval |
| Personality style transfer (DeepSeek imitation) | ✅ simplified by 87% |
### Missed Report Analysis (4 unreported updates)
All are **indirect conflicts** (require reasoning "moving to Shenzhen" implies "not living in Chengdu"),
which exceed pure semantic similarity capabilities. This is a known requires deeper reasoning-of-thought NLI to solve.
## File Structure
```
memory_engine engine.py # core engine (pipeline + integrate all modules)
├── fact_store.py # fact layer (RAG + trust additive weighting + superseded)
├── conflict_detector.py # conflict detection when writing (gradient down-weighting)
├── usage_feedback.py # usage feedback loop (only reinforce if adopted)
├── health_monitor.py # memory health monitoring (degradation alarm + cleanup suggestion)
├── partitioned_memory.py # personality memory partitioning (isolation + sharing)
├── persona_manager.py # multi-adapter personality (LoRA switching)
├── deepseek_client.py # DeepSeek client
└── service.py # HTTP service
eval/
├── test_stress.py # stress test (105 entries, conflict + compatible + health)
├── test_conflict.py # conflict detection test
├── test_new_features.py # comprehensive test of feedback + health + partitioning
├── test_evolution.py # longitudinal evolution eval (200 rounds)
├── test_mao_compare.py # Mao Zedong thought comparison (verify personality boundary)
├── test_contrarian.py # contrarian decision-making comparison
test_trust.py # trust layer unit test
test_smoke.py # end-to-end smoke test
test_persona.py # personality layer test
```
## Known Limitations
- Indirect conflicts (require reasoning chain) cannot be detected by pure semantic similarity
- Large model thinking styles (e.g., Mao Zedong's) cannot be taught by small models
- Personality layer suitable for teaching "how to speak" (style), not "how to think" (deep reasoning)
- Trust decay cannot be verified in short-term testing (requires real time span)
- DeepSeek NLI judgment has latency (~700ms/entry), and large batch writing requires asynchronous processing
## RWKV AgentDual-Channel Memory)
RWKV for hot layer reasoning + memory-engine for cold layer fact library.
See [docs/RWKV_INTEGRATION.md](docs/RWKV_INTEGRATION.md) for details.
```python
from memory_engine import RwkvMemoryAgent, from_rwkv_local, from_rwkv_runner
from memory_engine.llm_backend import MockChatBackend
# smoke test (no RWKV)
agent = RwkvMemoryAgent(store_dir="./data", backend=MockChatBackend())
agent.add_fact("user is named Lin Wei.", pinned=True)
print(agent.chat("What's my name?")["response"])
# run RWKV locally with transformers (no HTTP service)
# agent = from_rwkv_local(store_dir="./data")
# run RWKV with OpenAI-compatible HTTP service: first run python scripts/rwkv_openai_server.py --cpu
# agent = from_rwkv_runner(base_url="http://127.0.0.1:8000/v1", model="rwkv")
```
```powershell
python test_rwkv_agent.py # mock smoke test
python scripts/run_rwkv_local_demo.py --cpu # local RWKV + BGE
python scripts/rwkv_openai_server.py --cpu # OpenAI-compatible HTTP service
```
## Integration with Other Systems
This service is an independent process with a pure HTTP interface.
Any host that can send HTTP requests can access it:
- call `/chat` for the service to complete the entire process
- or call `/facts/*` to manage memory yourself, using your own prompt logic
- use `GET /health` as a readiness probe
