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

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

python -m venv venv
venv\Scripts\activate

Step 2: Install Dependencies

pip install -e .

Step 3: Cold Start Init Core Memory

python scripts/init_core_memory.py

Step 4: Start MCP Server

firmmem-mcp

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

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 生成）