GitHub - gitstq/MemForge: 🧠 MemForge - Lightweight AI Agent Semantic Memory & Context Persistence Engine | 轻量级AI Agent语义记忆与上下文持久化引擎

简体中文 | 繁體中文 | English

 ██████╗ ██████╗ ███╗   ██╗ ██████╗ ██████╗ ███████╗
██╔════╝██╔═══██╗████╗  ██║██╔════╝ ██╔══██╗██╔════╝
██║     ██║   ██║██╔██╗ ██║██║  ███╗██████╔╝█████╗
██║     ██║   ██║██║╚██╗██║██║   ██║██╔══██╗██╔══╝
╚██████╗╚██████╔╝██║ ╚████║╚██████╔╝██║  ██║███████╗
 ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝

轻量级 AI Agent 语义记忆与上下文持久化引擎
Lightweight AI Agent Semantic Memory & Context Persistence Engine

简体中文

🎉 项目介绍

MemForge 是一款专为 AI Agent 设计的轻量级语义记忆与上下文持久化引擎。它让 AI Agent 拥有真正的「长期记忆」能力 -- 跨会话存储、语义检索、自动压缩，让每一次对话都能站在过往经验的肩膀上。

🔥 解决的核心痛点

Agent 记忆断层：当前大多数 AI Agent 在会话结束后便「失忆」，无法复用历史经验，导致重复犯错、上下文丢失
外部依赖过重：现有方案（如 agentmemory）依赖 Node.js 运行时、需要 OpenAI API Key 才能生成向量嵌入，部署成本高、网络受限场景无法使用
缺乏语义理解：简单的键值存储无法理解「认证方式」和「JWT 鉴权」之间的语义关联，检索效果差
记忆无限膨胀：缺少自动压缩和合并机制，记忆数据随时间线性增长，最终拖慢检索性能

🌟 自研差异化亮点

特性	MemForge	agentmemory 等方案
外部依赖	零依赖，纯 Python + SQLite3	依赖 Node.js、npm 生态
向量嵌入	本地 TF-IDF，无需 API Key	需要 OpenAI API
知识图谱	内置，自动实体抽取与关联	需额外集成
存储引擎	SQLite3，单文件、零运维	依赖外部数据库
部署方式	`pip install` 即用	需安装 Node.js 环境
网络要求	完全离线可用	依赖外部 API

💡 灵感来源

灵感来自对 AI Agent 长期记忆能力的持续思考：如何让 Agent 像「铁匠锻造」一样，将每次交互的经验不断锻造成持久可用的知识？MemForge（记忆锻造炉）因此得名 -- 它不仅存储记忆，更通过语义嵌入、知识图谱和智能压缩，将原始信息锻造成高质量的结构化知识。

✨ 核心特性

🧠 本地 TF-IDF 向量嵌入 -- 基于词频-逆文档频率算法，纯 Python 实现，零网络依赖，支持 N-gram 和停用词过滤
🕸️ 内置知识图谱 -- 自动从记忆内容中抽取实体，构建实体关系网络，支持多跳关联查询
🔍 双模式语义搜索 -- 向量语义搜索 + SQLite FTS5 全文搜索，覆盖精确匹配与模糊语义两种场景
🗜️ 智能记忆压缩 -- 自动检测相似记忆并合并，提取关键洞见，防止记忆无限膨胀
📡 HTTP REST API -- 内置轻量 HTTP 服务器（默认端口 8420），支持 CORS，可被任何语言调用
🖥️ 功能完整的 CLI 工具 -- 13 个子命令覆盖记忆的增删改查、压缩、洞察提取、图谱查询、数据导出等全部操作
📂 会话管理 -- 支持多 Agent、多会话隔离，每个会话独立管理记忆生命周期
🏷️ 多维记忆分类 -- 7 种记忆类型（事实/偏好/上下文/决策/错误/技能/摘要）+ 4 级重要度 + 自定义标签
🔐 API Key 鉴权 -- 可选的 API Key 认证机制，保护记忆服务安全
📦 零外部依赖 -- 纯 Python 标准库 + SQLite3，pip install 即可使用，无需安装任何第三方包
💾 SQLite3 持久化 -- WAL 模式、自动 VACUUM、64MB 缓存，单文件存储，零运维成本

🚀 快速开始

📋 环境要求

Python 3.8+（支持 3.8 / 3.9 / 3.10 / 3.11 / 3.12）
无需任何第三方依赖

📥 安装

# 方式一：从源码安装（推荐）
git clone https://github.com/gitstq/MemForge.git
cd MemForge
pip install .

# 方式二：本地开发模式
cd MemForge
pip install -e .

# 方式三：直接运行（无需安装）
cd MemForge
PYTHONPATH=src python -m memforge --help

🏃 本地启动

# 启动 HTTP API 服务器
memforge serve

# 运行交互式 Demo
memforge demo

# 存储一条记忆
memforge remember "项目使用 FastAPI 作为后端框架"

# 语义搜索记忆
memforge recall "后端技术栈"

# 查看统计信息
memforge stats

⚡ 三行代码上手

from memforge.engine import MemForge

mf = MemForge().initialize()
mf.remember("项目使用 PostgreSQL 数据库，连接池上限 20")
results = mf.recall("数据库配置")

📖 详细使用指南

🖥️ CLI 命令一览

MemForge 提供了 13 个功能完整的 CLI 子命令：

命令	说明	示例
`serve`	启动 HTTP API 服务器	`memforge serve --port 9000`
`remember`	存储一条新记忆	`memforge remember "内容" --type fact --importance 3`
`recall`	语义搜索记忆	`memforge recall "查询关键词" --limit 5 --mode semantic`
`forget`	删除一条记忆	`memforge forget <memory_id> --hard`
`list`	列出所有记忆	`memforge list --session <id> --type fact`
`sessions`	列出所有会话	`memforge sessions --agent <agent_id>`
`stats`	显示统计信息	`memforge stats`
`compress`	压缩会话记忆	`memforge compress <session_id>`
`insights`	提取关键洞见	`memforge insights --session <id> --top 5`
`graph`	知识图谱操作	`memforge graph related --label "FastAPI"`
`demo`	运行交互式 Demo	`memforge demo`
`export`	导出记忆为 JSON	`memforge export --output memories.json`

记忆类型：fact（事实）、preference（偏好）、context（上下文）、decision（决策）、error（错误）、skill（技能）、summary（摘要）

重要度等级：1（低）、2（中）、3（高）、4（关键）

🐍 Python API

from memforge.engine import MemForge
from memforge.core.config import MemForgeConfig

# 自定义配置
config = MemForgeConfig()
config.storage.db_path = "~/.memforge/my_project.db"
config.embedding.vector_dim = 128
config.graph.enabled = True

# 初始化引擎
mf = MemForge(config).initialize()

# 创建会话
session_id = mf.create_session(agent_id="my-agent", title="开发会话")

# 存储记忆（支持 7 种类型 + 4 级重要度 + 自定义标签）
mf.remember(
    "使用 JWT 进行用户认证，access_token 有效期 2 小时",
    memory_type="fact",
    importance=3,
    session_id=session_id,
    tags=["auth", "security"]
)

# 语义搜索（默认模式）
results = mf.recall("认证方式", limit=5, session_id=session_id)
for r in results:
    print(f"[{r.score:.4f}] {r.memory.content}")

# 全文搜索
results = mf.recall("JWT", limit=5, mode="fulltext")

# 获取单条记忆 / 更新 / 删除
memory = mf.get_memory(memory_id)
mf.update_memory(memory_id, importance=4)
mf.forget(memory_id, soft=True)  # 软删除（归档）

# 提取关键洞见
insights = mf.extract_insights(session_id=session_id, top_k=5)

# 压缩会话记忆
stats = mf.compress_session(session_id)

# 知识图谱查询
related = mf.get_related_entities("FastAPI", depth=1)
context = mf.get_entity_context("PostgreSQL")

# 获取统计信息
stats = mf.stats()

# 启动 HTTP 服务器
mf.serve(host="0.0.0.0", port=8420)

# 关闭连接
mf.close()

📡 HTTP API

启动服务器后（默认 http://127.0.0.1:8420），可通过 REST API 进行所有操作：

# 健康检查
curl http://127.0.0.1:8420/api/health

# 存储记忆
curl -X POST http://127.0.0.1:8420/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "项目使用 Redis 做缓存", "type": "fact", "importance": 3}'

# 语义搜索
curl -X POST http://127.0.0.1:8420/api/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "缓存方案", "limit": 5}'

# 列出记忆
curl "http://127.0.0.1:8420/api/memories?limit=20&session_id=xxx"

# 获取单条记忆
curl http://127.0.0.1:8420/api/memories/<memory_id>

# 删除记忆
curl -X DELETE http://127.0.0.1:8420/api/memories/<memory_id>

# 全文搜索
curl "http://127.0.0.1:8420/api/search?q=FastAPI&limit=10"

# 获取统计信息
curl http://127.0.0.1:8420/api/stats

# 创建会话
curl -X POST http://127.0.0.1:8420/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"title": "新会话", "agent_id": "agent-1"}'

# 列出会话
curl "http://127.0.0.1:8420/api/sessions?agent_id=agent-1"

# 压缩会话记忆
curl -X POST http://127.0.0.1:8420/api/compress \
  -H "Content-Type: application/json" \
  -d '{"session_id": "xxx"}'

# 知识图谱 - 查询关联实体
curl -X POST http://127.0.0.1:8420/api/graph/related \
  -H "Content-Type: application/json" \
  -d '{"label": "FastAPI", "depth": 1}'

API 鉴权：设置环境变量 MEMFORGE_API_KEY=your_key 后，请求需携带 X-API-Key 或 Authorization: Bearer <key> 头。

⚙️ 环境变量配置

环境变量	说明	默认值
`MEMFORGE_DB_PATH`	数据库文件路径	`~/.memforge/memories.db`
`MEMFORGE_HOST`	HTTP 服务器监听地址	`127.0.0.1`
`MEMFORGE_PORT`	HTTP 服务器端口	`8420`
`MEMFORGE_API_KEY`	API 鉴权密钥（可选）	无
`MEMFORGE_LOG_LEVEL`	日志级别	`INFO`
`MEMFORGE_DEBUG`	调试模式	`false`
`MEMFORGE_EMBEDDING_MODEL`	嵌入模型（tfidf/bow/hash）	`tfidf`
`MEMFORGE_VECTOR_DIM`	向量维度	`256`
`MEMFORGE_GRAPH_ENABLED`	是否启用知识图谱	`true`
`MEMFORGE_COMPRESS_ENABLED`	是否启用自动压缩	`true`

💡 设计思路与迭代规划

🎨 设计哲学

极简主义：零外部依赖，纯 Python 标准库实现，降低使用门槛和部署复杂度
离线优先：所有计算在本地完成，不依赖任何外部 API，适合内网、离线、隐私敏感场景
渐进增强：从简单的键值存储到语义搜索、知识图谱、自动压缩，按需启用
Agent 友好：同时提供 Python API、CLI 和 HTTP API 三种接入方式，适配各种 Agent 架构

🔧 技术选型

模块	技术方案	选型理由
向量嵌入	TF-IDF + N-gram	纯 Python 实现，无需外部模型，适合中短文本语义匹配
存储	SQLite3 + WAL	零运维、单文件、支持 FTS5 全文搜索、事务安全
知识图谱	邻接表 + 关系表	轻量实现，支持多跳查询，与记忆存储无缝集成
HTTP 服务	`http.server` 标准库	零依赖，满足 REST API 需求
记忆压缩	相似度检测 + 合并	基于向量余弦相似度自动合并冗余记忆

🗺️ 迭代规划

v1.0.0 -- 核心引擎：TF-IDF 嵌入、语义搜索、知识图谱、记忆压缩、HTTP API、CLI
v1.1.0 -- MCP（Model Context Protocol）服务器集成，支持 Claude 等模型直接调用
v1.2.0 -- 记忆过期与衰减机制，基于访问频率和时间的自动遗忘策略
v1.3.0 -- 多语言嵌入优化，支持中英文混合场景的语义匹配增强
v2.0.0 -- 可选外部嵌入后端（sentence-transformers），兼顾离线与高精度需求

📦 打包与部署指南

📌 pip 安装

# 从 PyPI 安装（发布后）
pip install memforge

# 从源码安装
git clone https://github.com/gitstq/MemForge.git
cd MemForge
pip install .

安装后 memforge 命令自动注册到 PATH，可直接使用。

🐳 Docker 部署

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install --no-cache-dir .

# 数据持久化
VOLUME ["/root/.memforge"]
EXPOSE 8420

ENV MEMFORGE_HOST=0.0.0.0
ENV MEMFORGE_PORT=8420

CMD ["memforge", "serve"]

# 构建并运行
docker build -t memforge .
docker run -d -p 8420:8420 -v memforge-data:/root/.memforge memforge

🌍 环境变量部署

# 生产环境推荐配置
export MEMFORGE_DB_PATH=/data/memforge/memories.db
export MEMFORGE_HOST=0.0.0.0
export MEMFORGE_PORT=8420
export MEMFORGE_API_KEY=your_secure_key_here
export MEMFORGE_LOG_LEVEL=WARNING
export MEMFORGE_DEBUG=false

memforge serve

🤝 贡献指南

我们欢迎任何形式的贡献！无论是 Bug 报告、功能建议还是代码提交。

📝 提交 PR

Fork 本仓库并创建特性分支：git checkout -b feature/your-feature
编写代码并确保通过测试：python -m pytest tests/
提交并推送：git commit -m "feat: add your feature" + git push
发起 Pull Request，详细描述改动内容

🐛 提交 Issue

Bug 报告：请附上复现步骤、预期行为、实际行为、Python 版本和运行环境
功能建议：请描述使用场景、期望行为，以及为什么现有功能无法满足需求
问题讨论：使用 GitHub Discussions 进行开放式讨论

📋 代码规范

遵循 PEP 8 编码规范
添加适当的类型注解
为新功能编写单元测试
保持零外部依赖的原则

📄 开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Made with ❤️ by gitstq | ⭐ 如果觉得有用，请给个 Star！

繁體中文

🎉 項目介紹

MemForge 是一款專為 AI Agent 設計的輕量級語義記憶與上下文持久化引擎。它讓 AI Agent 擁有真正的「長期記憶」能力 -- 跨會話儲存、語義檢索、自動壓縮，讓每一次對話都能站在過往經驗的基礎上。

🔥 解決的核心痛點

Agent 記憶斷層：目前大多數 AI Agent 在會話結束後便「失憶」，無法複用歷史經驗，導致重複犯錯、上下文遺失
外部依賴過重：現有方案（如 agentmemory）依賴 Node.js 執行環境、需要 OpenAI API Key 才能生成向量嵌入，部署成本高、網路受限場景無法使用
缺乏語義理解：簡單的鍵值儲存無法理解「認證方式」和「JWT 鑑權」之間的語義關聯，檢索效果差
記憶無限膨脹：缺少自動壓縮與合併機制，記憶資料隨時間線性增長，最終拖慢檢索效能

🌟 自研差異化亮點

特性	MemForge	agentmemory 等方案
外部依賴	零依賴，純 Python + SQLite3	依賴 Node.js、npm 生態
向量嵌入	本地 TF-IDF，無需 API Key	需要 OpenAI API
知識圖譜	內建，自動實體抽取與關聯	需額外整合
儲存引擎	SQLite3，單檔案、零維運	依賴外部資料庫
部署方式	`pip install` 即用	需安裝 Node.js 環境
網路需求	完全離線可用	依賴外部 API

💡 靈感來源

靈感來自對 AI Agent 長期記憶能力的持續思考：如何讓 Agent 像「鐵匠鍛造」一樣，將每次互動的經驗不斷鍛造成持久可用的知識？MemForge（記憶鍛造爐）因此得名 -- 它不僅儲存記憶，更透過語義嵌入、知識圖譜和智慧壓縮，將原始資訊鍛造成高品質的結構化知識。

✨ 核心特性

🧠 本地 TF-IDF 向量嵌入 -- 基於詞頻-逆文件頻率演算法，純 Python 實作，零網路依賴，支援 N-gram 和停用詞過濾
🕸️ 內建知識圖譜 -- 自動從記憶內容中抽取實體，建構實體關聯網路，支援多跳關聯查詢
🔍 雙模式語義搜尋 -- 向量語義搜尋 + SQLite FTS5 全文搜尋，涵蓋精確匹配與模糊語義兩種場景
🗜️ 智慧記憶壓縮 -- 自動偵測相似記憶並合併，提取關鍵洞見，防止記憶無限膨脹
📡 HTTP REST API -- 內建輕量 HTTP 伺服器（預設連接埠 8420），支援 CORS，可被任何語言呼叫
🖥️ 功能完整的 CLI 工具 -- 13 個子命令涵蓋記憶的增刪改查、壓縮、洞見提取、圖譜查詢、資料匯出等全部操作
📂 會話管理 -- 支援多 Agent、多會話隔離，每個會話獨立管理記憶生命週期
🏷️ 多維記憶分類 -- 7 種記憶類型（事實/偏好/上下文/決策/錯誤/技能/摘要）+ 4 級重要度 + 自訂標籤
🔐 API Key 鑑權 -- 可選的 API Key 認證機制，保護記憶服務安全
📦 零外部依賴 -- 純 Python 標準函式庫 + SQLite3，pip install 即可使用，無需安裝任何第三方套件
💾 SQLite3 持久化 -- WAL 模式、自動 VACUUM、64MB 快取，單檔案儲存，零維運成本

🚀 快速開始

📋 環境需求

Python 3.8+（支援 3.8 / 3.9 / 3.10 / 3.11 / 3.12）
無需任何第三方依賴

📥 安裝

# 方式一：從原始碼安裝（推薦）
git clone https://github.com/gitstq/MemForge.git
cd MemForge
pip install .

# 方式二：本地開發模式
cd MemForge
pip install -e .

# 方式三：直接執行（無需安裝）
cd MemForge
PYTHONPATH=src python -m memforge --help

🏃 本地啟動

# 啟動 HTTP API 伺服器
memforge serve

# 執行互動式 Demo
memforge demo

# 儲存一條記憶
memforge remember "專案使用 FastAPI 作為後端框架"

# 語義搜尋記憶
memforge recall "後端技術棧"

# 檢視統計資訊
memforge stats

⚡ 三行程式碼上手

from memforge.engine import MemForge

mf = MemForge().initialize()
mf.remember("專案使用 PostgreSQL 資料庫，連線池上限 20")
results = mf.recall("資料庫配置")

📖 詳細使用指南

🖥️ CLI 命令一覽

MemForge 提供了 13 個功能完整的 CLI 子命令：

命令	說明	範例
`serve`	啟動 HTTP API 伺服器	`memforge serve --port 9000`
`remember`	儲存一條新記憶	`memforge remember "內容" --type fact --importance 3`
`recall`	語義搜尋記憶	`memforge recall "查詢關鍵字" --limit 5 --mode semantic`
`forget`	刪除一條記憶	`memforge forget <memory_id> --hard`
`list`	列出所有記憶	`memforge list --session <id> --type fact`
`sessions`	列出所有會話	`memforge sessions --agent <agent_id>`
`stats`	顯示統計資訊	`memforge stats`
`compress`	壓縮會話記憶	`memforge compress <session_id>`
`insights`	提取關鍵洞見	`memforge insights --session <id> --top 5`
`graph`	知識圖譜操作	`memforge graph related --label "FastAPI"`
`demo`	執行互動式 Demo	`memforge demo`
`export`	匯出記憶為 JSON	`memforge export --output memories.json`

記憶類型：fact（事實）、preference（偏好）、context（上下文）、decision（決策）、error（錯誤）、skill（技能）、summary（摘要）

重要度等級：1（低）、2（中）、3（高）、4（關鍵）

🐍 Python API

from memforge.engine import MemForge
from memforge.core.config import MemForgeConfig

# 自訂配置
config = MemForgeConfig()
config.storage.db_path = "~/.memforge/my_project.db"
config.embedding.vector_dim = 128
config.graph.enabled = True

# 初始化引擎
mf = MemForge(config).initialize()

# 建立會話
session_id = mf.create_session(agent_id="my-agent", title="開發會話")

# 儲存記憶（支援 7 種類型 + 4 級重要度 + 自訂標籤）
mf.remember(
    "使用 JWT 進行使用者認證，access_token 有效期 2 小時",
    memory_type="fact",
    importance=3,
    session_id=session_id,
    tags=["auth", "security"]
)

# 語義搜尋（預設模式）
results = mf.recall("認證方式", limit=5, session_id=session_id)
for r in results:
    print(f"[{r.score:.4f}] {r.memory.content}")

# 全文搜尋
results = mf.recall("JWT", limit=5, mode="fulltext")

# 取得單條記憶 / 更新 / 刪除
memory = mf.get_memory(memory_id)
mf.update_memory(memory_id, importance=4)
mf.forget(memory_id, soft=True)  # 軟刪除（歸檔）

# 提取關鍵洞見
insights = mf.extract_insights(session_id=session_id, top_k=5)

# 壓縮會話記憶
stats = mf.compress_session(session_id)

# 知識圖譜查詢
related = mf.get_related_entities("FastAPI", depth=1)
context = mf.get_entity_context("PostgreSQL")

# 取得統計資訊
stats = mf.stats()

# 啟動 HTTP 伺服器
mf.serve(host="0.0.0.0", port=8420)

# 關閉連線
mf.close()

📡 HTTP API

啟動伺服器後（預設 http://127.0.0.1:8420），可透過 REST API 進行所有操作：

# 健康檢查
curl http://127.0.0.1:8420/api/health

# 儲存記憶
curl -X POST http://127.0.0.1:8420/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "專案使用 Redis 做快取", "type": "fact", "importance": 3}'

# 語義搜尋
curl -X POST http://127.0.0.1:8420/api/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "快取方案", "limit": 5}'

# 列出記憶
curl "http://127.0.0.1:8420/api/memories?limit=20&session_id=xxx"

# 取得單條記憶
curl http://127.0.0.1:8420/api/memories/<memory_id>

# 刪除記憶
curl -X DELETE http://127.0.0.1:8420/api/memories/<memory_id>

# 全文搜尋
curl "http://127.0.0.1:8420/api/search?q=FastAPI&limit=10"

# 取得統計資訊
curl http://127.0.0.1:8420/api/stats

# 建立會話
curl -X POST http://127.0.0.1:8420/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"title": "新會話", "agent_id": "agent-1"}'

# 列出會話
curl "http://127.0.0.1:8420/api/sessions?agent_id=agent-1"

# 壓縮會話記憶
curl -X POST http://127.0.0.1:8420/api/compress \
  -H "Content-Type: application/json" \
  -d '{"session_id": "xxx"}'

# 知識圖譜 - 查詢關聯實體
curl -X POST http://127.0.0.1:8420/api/graph/related \
  -H "Content-Type: application/json" \
  -d '{"label": "FastAPI", "depth": 1}'

API 鑑權：設定環境變數 MEMFORGE_API_KEY=your_key 後，請求需攜帶 X-API-Key 或 Authorization: Bearer <key> 標頭。

⚙️ 環境變數配置

環境變數	說明	預設值
`MEMFORGE_DB_PATH`	資料庫檔案路徑	`~/.memforge/memories.db`
`MEMFORGE_HOST`	HTTP 伺服器監聽位址	`127.0.0.1`
`MEMFORGE_PORT`	HTTP 伺服器連接埠	`8420`
`MEMFORGE_API_KEY`	API 鑑權金鑰（可選）	無
`MEMFORGE_LOG_LEVEL`	日誌層級	`INFO`
`MEMFORGE_DEBUG`	除錯模式	`false`
`MEMFORGE_EMBEDDING_MODEL`	嵌入模型（tfidf/bow/hash）	`tfidf`
`MEMFORGE_VECTOR_DIM`	向量維度	`256`
`MEMFORGE_GRAPH_ENABLED`	是否啟用知識圖譜	`true`
`MEMFORGE_COMPRESS_ENABLED`	是否啟用自動壓縮	`true`

💡 設計思路與迭代規劃

🎨 設計哲學

極簡主義：零外部依賴，純 Python 標準函式庫實作，降低使用門檻與部署複雜度
離線優先：所有運算在本地完成，不依賴任何外部 API，適合內網、離線、隱私敏感場景
漸進增強：從簡單的鍵值儲存到語義搜尋、知識圖譜、自動壓縮，按需啟用
Agent 友善：同時提供 Python API、CLI 和 HTTP API 三種接入方式，適配各種 Agent 架構

🔧 技術選型

模組	技術方案	選型理由
向量嵌入	TF-IDF + N-gram	純 Python 實作，無需外部模型，適合中短文本語義匹配
儲存	SQLite3 + WAL	零維運、單檔案、支援 FTS5 全文搜尋、交易安全
知識圖譜	鄰接表 + 關聯表	輕量實作，支援多跳查詢，與記憶儲存無縫整合
HTTP 服務	`http.server` 標準函式庫	零依賴，滿足 REST API 需求
記憶壓縮	相似度偵測 + 合併	基於向量餘弦相似度自動合併冗餘記憶

🗺️ 迭代規劃

v1.0.0 -- 核心引擎：TF-IDF 嵌入、語義搜尋、知識圖譜、記憶壓縮、HTTP API、CLI
v1.1.0 -- MCP（Model Context Protocol）伺服器整合，支援 Claude 等模型直接呼叫
v1.2.0 -- 記憶過期與衰減機制，基於存取頻率和時間的自動遺忘策略
v1.3.0 -- 多語言嵌入最佳化，支援中英文混合場景的語義匹配增強
v2.0.0 -- 可選外部嵌入後端（sentence-transformers），兼顧離線與高精度需求

📦 打包與部署指南

📌 pip 安裝

# 從 PyPI 安裝（發佈後）
pip install memforge

# 從原始碼安裝
git clone https://github.com/gitstq/MemForge.git
cd MemForge
pip install .

安裝後 memforge 命令自動註冊到 PATH，可直接使用。

🐳 Docker 部署

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install --no-cache-dir .

# 資料持久化
VOLUME ["/root/.memforge"]
EXPOSE 8420

ENV MEMFORGE_HOST=0.0.0.0
ENV MEMFORGE_PORT=8420

CMD ["memforge", "serve"]

# 建置並執行
docker build -t memforge .
docker run -d -p 8420:8420 -v memforge-data:/root/.memforge memforge

🌍 環境變數部署

# 生產環境推薦配置
export MEMFORGE_DB_PATH=/data/memforge/memories.db
export MEMFORGE_HOST=0.0.0.0
export MEMFORGE_PORT=8420
export MEMFORGE_API_KEY=your_secure_key_here
export MEMFORGE_LOG_LEVEL=WARNING
export MEMFORGE_DEBUG=false

memforge serve

🤝 貢獻指南

我們歡迎任何形式的貢獻！無論是 Bug 回報、功能建議還是程式碼提交。

📝 提交 PR

Fork 本儲存庫並建立特性分支：git checkout -b feature/your-feature
撰寫程式碼並確保通過測試：python -m pytest tests/
提交並推送：git commit -m "feat: add your feature" + git push
發起 Pull Request，詳細描述變更內容

🐛 提交 Issue

Bug 回報：請附上重現步驟、預期行為、實際行為、Python 版本和執行環境
功能建議：請描述使用場景、期望行為，以及為什麼現有功能無法滿足需求
問題討論：使用 GitHub Discussions 進行開放式討論

📋 程式碼規範

遵循 PEP 8 編碼規範
新增適當的型別註解
為新功能撰寫單元測試
保持零外部依賴的原則

📄 開源協議

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Made with ❤️ by gitstq | ⭐ 如果覺得有用，請給個 Star！

English

🎉 Introduction

MemForge is a lightweight semantic memory and context persistence engine purpose-built for AI Agents. It gives AI Agents genuine long-term memory capabilities -- cross-session storage, semantic retrieval, and automatic compression -- so every conversation builds on past experience.

🔥 Core Pain Points Solved

Agent Amnesia: Most AI Agents lose all context after a session ends, unable to reuse historical experience, leading to repeated mistakes and lost context
Heavy External Dependencies: Existing solutions (like agentmemory) require Node.js runtime and OpenAI API keys for vector embeddings, making deployment costly and impossible in network-restricted environments
Lack of Semantic Understanding: Simple key-value stores cannot grasp the semantic relationship between "authentication" and "JWT tokens", resulting in poor retrieval quality
Unbounded Memory Growth: Without automatic compression and merging, memory data grows linearly over time, eventually degrading retrieval performance

🌟 Differentiation Highlights

Feature	MemForge	agentmemory & similar
External Dependencies	Zero deps, pure Python + SQLite3	Requires Node.js, npm ecosystem
Vector Embeddings	Local TF-IDF, no API key needed	Requires OpenAI API
Knowledge Graph	Built-in, automatic entity extraction	Requires separate integration
Storage Engine	SQLite3, single-file, zero maintenance	Depends on external databases
Deployment	`pip install` and go	Requires Node.js setup
Network Requirement	Fully offline-capable	Depends on external APIs

💡 Inspiration

The inspiration comes from a persistent question about AI Agent long-term memory: how can an agent, like a blacksmith forging metal, continuously forge each interaction's experience into durable, reusable knowledge? Hence the name MemForge (Memory Forge) -- it doesn't just store memories; through semantic embeddings, knowledge graphs, and intelligent compression, it forges raw information into high-quality structured knowledge.

✨ Core Features

🧠 Local TF-IDF Vector Embeddings -- Term Frequency-Inverse Document Frequency algorithm, pure Python implementation, zero network dependency, with N-gram support and stop-word filtering
🕸️ Built-in Knowledge Graph -- Automatically extracts entities from memory content, builds entity-relationship networks, supports multi-hop associative queries
🔍 Dual-Mode Semantic Search -- Vector semantic search + SQLite FTS5 full-text search, covering both exact matching and fuzzy semantic scenarios
🗜️ Intelligent Memory Compression -- Automatically detects similar memories and merges them, extracts key insights, prevents unbounded memory growth
📡 HTTP REST API -- Built-in lightweight HTTP server (default port 8420), CORS enabled, callable from any language
🖥️ Full-Featured CLI Tool -- 13 subcommands covering all memory CRUD operations, compression, insight extraction, graph queries, and data export
📂 Session Management -- Multi-agent, multi-session isolation with independent memory lifecycle management per session
🏷️ Multi-Dimensional Memory Classification -- 7 memory types (fact/preference/context/decision/error/skill/summary) + 4 importance levels + custom tags
🔐 API Key Authentication -- Optional API key authentication to secure your memory service
📦 Zero External Dependencies -- Pure Python standard library + SQLite3, ready to use with pip install, no third-party packages needed
💾 SQLite3 Persistence -- WAL mode, auto VACUUM, 64MB cache, single-file storage, zero maintenance overhead

🚀 Quick Start

📋 Prerequisites

Python 3.8+ (supports 3.8 / 3.9 / 3.10 / 3.11 / 3.12)
No third-party dependencies required

📥 Installation

# Option 1: Install from source (recommended)
git clone https://github.com/gitstq/MemForge.git
cd MemForge
pip install .

# Option 2: Development mode
cd MemForge
pip install -e .

# Option 3: Run directly (no install needed)
cd MemForge
PYTHONPATH=src python -m memforge --help

🏃 Local Startup

# Start the HTTP API server
memforge serve

# Run the interactive demo
memforge demo

# Store a memory
memforge remember "Project uses FastAPI as the backend framework"

# Semantic search
memforge recall "backend tech stack"

# View statistics
memforge stats

⚡ Three Lines to Get Started

from memforge.engine import MemForge

mf = MemForge().initialize()
mf.remember("Project uses PostgreSQL database with connection pool limit of 20")
results = mf.recall("database configuration")

📖 Usage Guide

🖥️ CLI Commands Reference

MemForge provides 13 fully-featured CLI subcommands:

Command	Description	Example
`serve`	Start the HTTP API server	`memforge serve --port 9000`
`remember`	Store a new memory	`memforge remember "content" --type fact --importance 3`
`recall`	Semantic memory search	`memforge recall "keywords" --limit 5 --mode semantic`
`forget`	Delete a memory	`memforge forget <memory_id> --hard`
`list`	List all memories	`memforge list --session <id> --type fact`
`sessions`	List all sessions	`memforge sessions --agent <agent_id>`
`stats`	Show statistics	`memforge stats`
`compress`	Compress session memories	`memforge compress <session_id>`
`insights`	Extract key insights	`memforge insights --session <id> --top 5`
`graph`	Knowledge graph operations	`memforge graph related --label "FastAPI"`
`demo`	Run interactive demo	`memforge demo`
`export`	Export memories to JSON	`memforge export --output memories.json`

Memory Types: fact, preference, context, decision, error, skill, summary

Importance Levels: 1 (low), 2 (medium), 3 (high), 4 (critical)

🐍 Python API

from memforge.engine import MemForge
from memforge.core.config import MemForgeConfig

# Custom configuration
config = MemForgeConfig()
config.storage.db_path = "~/.memforge/my_project.db"
config.embedding.vector_dim = 128
config.graph.enabled = True

# Initialize the engine
mf = MemForge(config).initialize()

# Create a session
session_id = mf.create_session(agent_id="my-agent", title="Development Session")

# Store a memory (7 types + 4 importance levels + custom tags)
mf.remember(
    "JWT authentication with 2-hour access token expiry",
    memory_type="fact",
    importance=3,
    session_id=session_id,
    tags=["auth", "security"]
)

# Semantic search (default mode)
results = mf.recall("authentication approach", limit=5, session_id=session_id)
for r in results:
    print(f"[{r.score:.4f}] {r.memory.content}")

# Full-text search
results = mf.recall("JWT", limit=5, mode="fulltext")

# Get / update / delete a single memory
memory = mf.get_memory(memory_id)
mf.update_memory(memory_id, importance=4)
mf.forget(memory_id, soft=True)  # Soft delete (archive)

# Extract key insights
insights = mf.extract_insights(session_id=session_id, top_k=5)

# Compress session memories
stats = mf.compress_session(session_id)

# Knowledge graph queries
related = mf.get_related_entities("FastAPI", depth=1)
context = mf.get_entity_context("PostgreSQL")

# Get statistics
stats = mf.stats()

# Start HTTP server
mf.serve(host="0.0.0.0", port=8420)

# Close connections
mf.close()

📡 HTTP API

After starting the server (default: http://127.0.0.1:8420), all operations are available via REST API:

# Health check
curl http://127.0.0.1:8420/api/health

# Store a memory
curl -X POST http://127.0.0.1:8420/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "Project uses Redis for caching", "type": "fact", "importance": 3}'

# Semantic search
curl -X POST http://127.0.0.1:8420/api/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "caching strategy", "limit": 5}'

# List memories
curl "http://127.0.0.1:8420/api/memories?limit=20&session_id=xxx"

# Get a single memory
curl http://127.0.0.1:8420/api/memories/<memory_id>

# Delete a memory
curl -X DELETE http://127.0.0.1:8420/api/memories/<memory_id>

# Full-text search
curl "http://127.0.0.1:8420/api/search?q=FastAPI&limit=10"

# Get statistics
curl http://127.0.0.1:8420/api/stats

# Create a session
curl -X POST http://127.0.0.1:8420/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"title": "New Session", "agent_id": "agent-1"}'

# List sessions
curl "http://127.0.0.1:8420/api/sessions?agent_id=agent-1"

# Compress session memories
curl -X POST http://127.0.0.1:8420/api/compress \
  -H "Content-Type: application/json" \
  -d '{"session_id": "xxx"}'

# Knowledge graph - query related entities
curl -X POST http://127.0.0.1:8420/api/graph/related \
  -H "Content-Type: application/json" \
  -d '{"label": "FastAPI", "depth": 1}'

API Authentication: Set the environment variable MEMFORGE_API_KEY=your_key, then include the X-API-Key or Authorization: Bearer <key> header in your requests.

⚙️ Environment Variables

Variable	Description	Default
`MEMFORGE_DB_PATH`	Database file path	`~/.memforge/memories.db`
`MEMFORGE_HOST`	HTTP server listen address	`127.0.0.1`
`MEMFORGE_PORT`	HTTP server port	`8420`
`MEMFORGE_API_KEY`	API authentication key (optional)	None
`MEMFORGE_LOG_LEVEL`	Log level	`INFO`
`MEMFORGE_DEBUG`	Debug mode	`false`
`MEMFORGE_EMBEDDING_MODEL`	Embedding model (tfidf/bow/hash)	`tfidf`
`MEMFORGE_VECTOR_DIM`	Vector dimension	`256`
`MEMFORGE_GRAPH_ENABLED`	Enable knowledge graph	`true`
`MEMFORGE_COMPRESS_ENABLED`	Enable auto-compression	`true`

💡 Design & Roadmap

🎨 Design Philosophy

Minimalism: Zero external dependencies, pure Python standard library implementation, minimizing the barrier to entry and deployment complexity
Offline-First: All computation happens locally with no reliance on external APIs, ideal for intranet, offline, and privacy-sensitive environments
Progressive Enhancement: From simple key-value storage to semantic search, knowledge graphs, and automatic compression -- enable only what you need
Agent-Friendly: Three access methods (Python API, CLI, HTTP API) to fit any Agent architecture

🔧 Technical Choices

Component	Technology	Rationale
Vector Embeddings	TF-IDF + N-gram	Pure Python, no external models needed, ideal for short-to-medium text semantic matching
Storage	SQLite3 + WAL	Zero maintenance, single-file, FTS5 full-text search support, transaction-safe
Knowledge Graph	Adjacency list + relation tables	Lightweight implementation, multi-hop queries, seamless integration with memory storage
HTTP Server	`http.server` stdlib	Zero dependencies, meets REST API requirements
Memory Compression	Similarity detection + merging	Automatic merging of redundant memories based on cosine similarity

🗺️ Roadmap

v1.0.0 -- Core engine: TF-IDF embeddings, semantic search, knowledge graph, memory compression, HTTP API, CLI
v1.1.0 -- MCP (Model Context Protocol) server integration for direct invocation by Claude and similar models
v1.2.0 -- Memory expiration and decay mechanisms with automatic forgetting based on access frequency and time
v1.3.0 -- Multi-language embedding optimization for enhanced semantic matching in mixed Chinese-English scenarios
v2.0.0 -- Optional external embedding backends (sentence-transformers) for balancing offline capability with high-precision needs

📦 Packaging & Deployment

📌 pip Install

# Install from PyPI (after publication)
pip install memforge

# Install from source
git clone https://github.com/gitstq/MemForge.git
cd MemForge
pip install .

After installation, the memforge command is automatically registered to PATH and ready to use.

🐳 Docker Deployment

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install --no-cache-dir .

# Data persistence
VOLUME ["/root/.memforge"]
EXPOSE 8420

ENV MEMFORGE_HOST=0.0.0.0
ENV MEMFORGE_PORT=8420

CMD ["memforge", "serve"]

# Build and run
docker build -t memforge .
docker run -d -p 8420:8420 -v memforge-data:/root/.memforge memforge

🌍 Environment Variable Deployment

# Recommended production configuration
export MEMFORGE_DB_PATH=/data/memforge/memories.db
export MEMFORGE_HOST=0.0.0.0
export MEMFORGE_PORT=8420
export MEMFORGE_API_KEY=your_secure_key_here
export MEMFORGE_LOG_LEVEL=WARNING
export MEMFORGE_DEBUG=false

memforge serve

🤝 Contributing

Contributions of all kinds are welcome! Whether it's a bug report, feature suggestion, or code submission.

📝 Submitting a PR

Fork this repository and create a feature branch: git checkout -b feature/your-feature
Write code and ensure tests pass: python -m pytest tests/
Commit and push: git commit -m "feat: add your feature" + git push
Open a Pull Request with a detailed description of your changes

🐛 Submitting an Issue

Bug Reports: Please include reproduction steps, expected behavior, actual behavior, Python version, and runtime environment
Feature Requests: Describe the use case, expected behavior, and why existing features don't meet the need
Discussions: Use GitHub Discussions for open-ended conversations

📋 Code Standards

Follow PEP 8 coding conventions
Add appropriate type annotations
Write unit tests for new features
Maintain the zero-external-dependency principle

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 gitstq

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Made with ❤️ by gitstq | ⭐ If you find this useful, please give it a Star!

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
examples		examples
src/memforge		src/memforge
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

简体中文

🎉 项目介绍

🔥 解决的核心痛点

🌟 自研差异化亮点

💡 灵感来源

✨ 核心特性

🚀 快速开始

📋 环境要求

📥 安装

🏃 本地启动

⚡ 三行代码上手

📖 详细使用指南

🖥️ CLI 命令一览

🐍 Python API

📡 HTTP API

⚙️ 环境变量配置

💡 设计思路与迭代规划

🎨 设计哲学

🔧 技术选型

🗺️ 迭代规划

📦 打包与部署指南

📌 pip 安装

🐳 Docker 部署

🌍 环境变量部署

🤝 贡献指南

📝 提交 PR

🐛 提交 Issue

📋 代码规范

📄 开源协议

繁體中文

🎉 項目介紹

🔥 解決的核心痛點

🌟 自研差異化亮點

💡 靈感來源

✨ 核心特性

🚀 快速開始

📋 環境需求

📥 安裝

🏃 本地啟動

⚡ 三行程式碼上手

📖 詳細使用指南

🖥️ CLI 命令一覽

🐍 Python API

📡 HTTP API

⚙️ 環境變數配置

💡 設計思路與迭代規劃

🎨 設計哲學

🔧 技術選型

🗺️ 迭代規劃

📦 打包與部署指南

📌 pip 安裝

🐳 Docker 部署

🌍 環境變數部署

🤝 貢獻指南

📝 提交 PR

🐛 提交 Issue

📋 程式碼規範

📄 開源協議

English

🎉 Introduction

🔥 Core Pain Points Solved

🌟 Differentiation Highlights

💡 Inspiration

✨ Core Features

🚀 Quick Start

📋 Prerequisites

📥 Installation

🏃 Local Startup

⚡ Three Lines to Get Started

📖 Usage Guide

🖥️ CLI Commands Reference

🐍 Python API

📡 HTTP API

⚙️ Environment Variables

💡 Design & Roadmap

🎨 Design Philosophy

Packages