# FirmMem MCP Server — Adaptive Ebbinghaus RFM Memory

## English｜中文

# 1\. Overview / 项目简介

**FirmMem** is a **pure\-SQLite structured long\-term memory MCP server** designed specifically for AI Agent \(Hermes\) persistent memory management\.

It abandons traditional fixed exponential decay and hard\-coded K\-values, and implements a **human\-like Ebbinghaus adaptive memory model** \+ **4\-tier hierarchical memory system** \+**Trust confidence feedback mechanism** \+ **statistical anomaly detection** \+ **optional semantic rerank**\.

**No vector database required, fully offline, lightweight, deterministic score algebra\.**

---

**FirmMem** 是专为 AI 智能体（Hermes）设计的 **纯 SQLite 结构化长期记忆 MCP 服务**。

彻底摒弃传统固定指数衰减、硬编码 K 值短板，实现：**艾宾浩斯自适应遗忘模型 \+ 四层分层记忆 \+ 可信度 Trust 奖惩体系 \+ 正态分布脏记忆检测 \+ 可开关语义相似度重排**。

**无向量库依赖、完全离线、分数可解释、数学结构严谨、适合长期智能体人设与任务记忆沉淀。**

## 2\. Core Capabilities / 核心能力

- **Adaptive Ebbinghaus RFM**：Dynamic half\-life, no hard\-coded decay K value\. Memory consolidation \& review reinforcement\.

- **4\-Tier Memory Hierarchy**：`core / strategic / validated / draft` differentiated forgetting strategy

- **Trust Asymmetric Feedback**：Positive boost / negative penalty, auto\-correct memory weight

- **Statistical Anomaly Detection**：3σ normal distribution filtering for dirty/conflicted memory

- **Optional Semantic Rerank**：SQL primary \+ embedding secondary rerank \(toggleable\)

- **Background Async RFM iteration**：Non\-blocking periodic weight update

- **Namespace isolation**：Multi\-agent / multi\-task isolation

- **Progressive Disclosure**：Core first → Strategic → Validated → Draft

---

- **自适应艾宾浩斯 RFM**：动态半衰期，无固定硬编码 K 值，记忆复习强化巩固

- **四层记忆分层架构**：core/strategic/validated/draft 差异化遗忘策略

- **非对称 Trust 奖惩机制**：正向加分、负向重罚，自动修正错误记忆权重

- **正态分布 3σ 异常检测**：自动识别突变脏记忆、冲突记忆、异常分数

- **可开关语义重排**：主流程纯SQL高性能，可选向量语义增强

- **后台异步迭代权重**：不阻塞对话，周期性全局RFM刷新

- **命名空间隔离**：多智能体、多任务记忆隔离不污染

- **渐进披露召回**：优先核心人设 \-\> 战略目标 \-\> 关键事件 \-\> 临时对话

## 3\. Memory Tier Design / 四层记忆层级定义

### Core（永久核心记忆）

- Human setting, personality, fixed rules, hard constraints

- **No decay, trust=1\.0, locked**

- Only manually editable

### Strategic（战略长期记忆）

- Long\-term goals, global plans, ongoing missions

- Ultra\-long half\-life, slow decay

- Bind with goal\_id, strategic alignment scoring

### Validated（已验证关键记忆）

- Verified facts, confirmed interaction conclusions

- Medium half\-life, medium trust

### Draft（临时草稿记忆）

- Temporary chat fragments, unvalidated info

- Fast decay, low weight, auto\-eliminate over time

## 4\. Mathematical Model / 核心数学结构（解决硬编码K痛点）

### 4\.1 Ebbinghaus Adaptive Decay（No fixed K）

Effective half\-life dynamically changes with memory review frequency \& consolidation:

$effective\_half\_life = base\_half\_life \times (1 + consolidation\_base \times consolidation \times recall\_count)$

$decay = e^{-\frac{recency\_days}{effective\_half\_life}}$

### 4\.2 Final Composite Score

$FinalScore = RFM_{adapt} \times Trust \times StrategyAlign \times SemanticSim_{(toggleable)}$

### 4\.3 Normal Distribution 3σ Anomaly Detection

Use normal distribution statistics to filter outlier trust/rfm dirty memory, **not for decay calculation**\.

## 5\. Architecture Workflow / 运行机制

### Cold Start 冷启动

- Empty SQLite initialized

- Run `init_core_memory.py` to build baseline core facts

- Avoid memory drift in early stage

### Real\-time Writing 实时写入

- Original chat text **will not be saved**

- Only structured summary \+ tags \+ tier metadata saved

- sequential\-thinking draft branches do not pollute main memory

### Background Iteration 后台迭代

- Hourly adaptive RFM recalculate

- Daily normal distribution anomaly check

## 6\. Local Deployment / 本地部署教程（Windows）

### Step 1: Clone \& Env

```bash
git clone https://github.com/jiayoupengpeng/firmmem-mcp.git
cd firmmem-mcp

python -m venv venv
venv\Scripts\activate

```

### Step 2: Install Dependencies

```bash
pip install -e .

```

### Step 3: Cold Start Init Core Memory

```bash
python scripts/init_core_memory.py

```

### Step 4: Start MCP Server

```bash
firmmem-mcp

```

## 7\. Hermes Agent Access Config / Hermes 接入配置

```yaml
mcp_servers:
  firmmem:
    command: firmmem-mcp
    args: []
    env:
      FIRMMEM_DB: ./firmmem.db
      DEFAULT_NAMESPACE: "hermes_default"
      ENABLE_SEMANTIC_RERANK: false

```

## 8\. Environment Config / 环境变量说明 \(\.env\.example\)

- `DRAFT_BASE_HALF_LIFE`：临时记忆基线半衰期

- `VALIDATED_BASE_HALF_LIFE`：验证记忆基线半衰期

- `STRATEGIC_BASE_HALF_LIFE`：战略记忆基线半衰期

- `CONSOLIDATION_BASE`：艾宾浩斯巩固系数

- `FEEDBACK_POS_DELTA / NEG_DELTA`：Trust 奖惩步长

- `ENABLE_SEMANTIC_RERANK`：是否开启语义相似度重排

- `NORMAL_STD_THRESHOLD`：正态异常检测阈值（默认3σ）

## 9\. MCP Tools List / 对外开放工具

- `firmmem_write_core_fact`：写入永久核心记忆

- `firmmem_write_strategic_memory`：写入长期战略记忆

- `firmmem_write_event_memory`：写入普通事件记忆

- `firmmem_recall_memory`：渐进式记忆召回

- `firmmem_memory_feedback`：记忆正负反馈、修正Trust

- `firmmem_archive_memory`：归档过期/无效记忆

## 10\. Project Advantages / 项目优势对比传统记忆

- ? **Traditional**：Fixed K decay, hard\-coded, no trust, no hierarchy, noisy chat saved

- ? **FirmMem v0\.2**：Adaptive Ebbinghaus math, tier isolation, trust feedback, semantic optional, statistical cleaning, pure SQL stable

## 11\. License

**MIT License**

Copyright \(c\) 2026 FirmMem

Open source for personal and commercial use, keep license header\.

> （注：部分内容可能由 AI 生成）