memctl
一个文件,一个真相。为你的LLMs记忆。
用于LLM编排的Unix本机内存控制平面——零依赖、策略控制、MCP本机
  ](https://github.com/ovitrac/memctl/releases)    
为什么选择memctl • 快速开始 • 克劳德代码的生态 • 安装 • CLI参考 • MCP服务器 • 运作原理
______________________________________________________________________
为什么选择memctl?
刚接触memctl? 查看完整 快速入门指南 常见问题解答、兼容性矩阵和故障排除。
LLMs在转弯之间会忘记一切。memctl为它们提供了由单个SQLite文件支持的持久、结构化、策略管理的内存。
- 零依赖 --仅限stdlib。没有numpy,没有torch,没有编译扩展。
- 一个文件 --一切都在
memory.db(SQLite+FTS5+WAL)。 - Unix可组合 —
push写入stdout,pull从stdin读取。管道自由。 - 政策管辖 --35种检测模式在存储之前会阻止秘密、注射、教学内容和PII。
- 寻址的内容 --SHA-256去重确保幂等摄取。
- 向前兼容 --与的架构相同 拉吉克斯。无缝升级。
______________________________________________________________________
安装
pip install memctl或与 pipx 对于独立的CLI安装:
pipx install memctl对于MCP服务器支持(克劳德代码/克劳德桌面):
pip install memctl[mcp] # pip
pipx install "memctl[mcp]" # pipx (recommended for CLI use)对于Office/ODF文档摄取(.docx、.odt、.pptx、.odp、.xlsx、.ods):
pip install memctl[docs]
pipx inject memctl python-docx python-pptx openpyxl odfpy pypdf # pipx对于一切:
pip install memctl[all]
pipx install "memctl[all]" # pipx要求: Python 3.10+(推荐3.12)。核心没有编译依赖项。 PDF提取使用 pypdf (通过 [docs] 额外),并回退到 pdftotext (poppler-utils)。
______________________________________________________________________
快速入门
1.初始化内存工作区
memctl init
# Creates .memory/memory.db, .memory/config.json, .memory/.gitignore为方便起见,设置环境变量:
eval $(memctl init)
# Sets MEMCTL_DB=.memory/memory.db2.摄入文件和召回
# Ingest source files + recall matching items → injection block on stdout
memctl push "authentication flow" --source src/auth/
# Ingest Office documents (requires memctl[docs])
memctl push "project status" --source reports/*.docx slides/*.pptx
# Ingest PDFs (requires pdftotext)
memctl push "specifications" --source specs/*.pdf
# Recall only (no ingestion)
memctl push "database schema"3.存储LLM输出
# Pipe LLM output into memory
echo "We chose JWT for stateless auth" | memctl pull --tags auth,decision --title "Auth decision"
# Or pipe from any LLM CLI
memctl push "API design" | llm "Analyze this" | memctl pull --tags api4.搜索
# Human-readable
memctl search "authentication"
# JSON for scripts
memctl search "database" --json -k 55.检查文件夹(单层)
# Auto-mounts, auto-syncs, and inspects — all in one command
memctl inspect docs/
# Same in JSON (for scripts)
memctl inspect docs/ --json
# Skip sync (use cached state)
memctl inspect docs/ --no-syncinspect 如果需要,自动挂载文件夹,检查过时性,仅在过时时进行同步,并生成结构化摘要。所有隐式操作都在stderr上宣布。
6.问一个关于文件夹的问题
# One-shot: auto-mount, auto-sync, inspect + recall → LLM → answer
memctl ask docs/ "What authentication risks exist?" --llm "claude -p"
# With Ollama
memctl ask src/ "What is under-documented?" --llm "ollama run granite3.1:2b"
# JSON output with metadata
memctl ask docs/ "Summarize the architecture" --llm "claude -p" --jsonask 将挂载、同步、结构检查和范围调用组合到一个命令中。LLM接收文件夹结构和内容上下文。
7.使用内存支持的上下文聊天
# Interactive chat with any LLM
memctl chat --llm "claude -p" --session
# With pre-ingested files and answer storage
memctl chat --llm "ollama run granite3.1:2b" --source docs/ --store --session每个问题都会从内存中调用,将上下文+问题发送到LLM,并显示答案。 --session 保持最近问答对的滑动窗口。 --store 将答案作为STM项目保留。
8.管理
memctl show MEM-abc123def456 # Show item details
memctl stats # Store metrics
memctl stats --json # Machine-readable stats
memctl consolidate # Merge similar STM items
memctl consolidate --dry-run # Preview without writing______________________________________________________________________
CLI参考
memctl [options]命令
| 命令 | 描述 | ||
|---|---|---|---|
init [PATH] | 初始化内存工作区(默认值: .memory) | ||
push QUERY [--source ...] | 摄取文件+将匹配的项目调用到stdout | ||
pull [--tags T] [--title T] | 读取stdin,存储为内存项 | ||
search QUERY [-k N] | FTS5全文搜索 | ||
show ID | 显示单个内存项 | ||
stats | 店铺统计 | ||
status | 项目内存运行状况仪表板 | ||
| `eco [on\ | off\ | status]` | 切换生态模式(开/关/状态) |
consolidate [--dry-run] | 相似STM项目的确定性合并 | ||
loop QUERY --llm CMD | LLM的有界召回应答循环 | ||
mount PATH | 将文件夹注册为结构化源 | ||
sync [PATH] | 增量同步将文件夹装载到存储中 | ||
inspect [PATH] | 自动安装和自动同步的结构检查 | ||
ask PATH "Q" --llm CMD | 一次性文件夹问答(检查+范围召回+循环) | ||
chat --llm CMD | 交互式内存支持聊天REPL | ||
export [--tier T] | 将内存项作为JSONL导出到stdout | ||
import [FILE] | 从JSONL文件或stdin导入内存项 | ||
promote ID [--tier T] | 将项目提升到更高级别(STM→MTM→LTM) | ||
diff ID1 [ID2] | 比较两个项目或项目与修订 | ||
reindex [--tokenizer P] | 重建FTS5索引(可选择使用新的标记器) | ||
reset [--confirm] | 截断所有内存内容(保留架构+装载) | ||
doctor [--json] | 环境健康检查(10项诊断检查) | ||
hooks | 运行克劳德代码挂钩(生态提示、生态轻推、安全防护、审计记录器) | ||
hooks-path | 打印包含钩子模板脚本的目录 | ||
setup | 安装集成(mcp, eco,或 hooks)--跨平台 | ||
teardown | 删除集成(mcp, eco,或 hooks)--跨平台 | ||
scripts-path | 打印捆绑安装程序脚本的路径 | ||
serve [--transport T] | 启动MCP服务器(stdio/streamable-http/sse) |
全球旗帜
| 标志 | 描述 |
|---|---|
--db PATH | SQLite数据库路径 |
--config PATH | 通往 config.json (在数据库旁自动检测到) |
--json | 机器可读JSON输出 |
-q, --quiet | 抑制stderr进度消息 |
-v, --verbose | 启用调试日志记录 |
命令详细信息
memctl init
memctl init [PATH] [--force] [--fts-tokenizer fr|en|raw]创建工作区目录、带模式的SQLite数据库、, config.json,以及 .gitignore.打印 export MEMCTL_DB="..." 到stdout进行eval。
Idempotent:在同一路径上运行两次,无错误退出0。
memctl push
memctl push QUERY [--source FILE ...] [--budget N] [--tier TIER] [--tags T] [--scope S]两相指令:
- 摄取 (可选):流程
--source使用SHA-256去重和段落分块的文件。 - 召回:FTS5搜索QUERY,将匹配项格式化为stdout上的注入块。
stdout只包含注入块(format_version=1).进度转到stderr。
memctl pull
echo "..." | memctl pull [--tags T] [--title T] [--scope S]从stdin读取文本并将其存储为内存项。首先尝试结构化提案提取;退回到单张存储。所有内容在存储之前都会经过策略引擎。
memctl search
memctl search QUERY [--tier TIER] [--type TYPE] [-k N] [--json]FTS5全文搜索。默认情况下返回人类可读的输出,或JSON --json.
memctl consolidate
memctl consolidate [--scope S] [--dry-run] [--json]确定性整合:按类型+标签重叠(Jaccard)对STM项目进行聚类,合并每个聚类(最长内容获胜),升级为MTM。高使用率的MTM项目会升级为LTM。没有LLM电话。
memctl loop
memctl push "question" | memctl loop "question" --llm "claude -p" [--max-calls 3] [--protocol json]有界召回应答循环:将上下文+问题发送到外部LLM,解析其响应以获取细化指令,从内存存储中执行额外的召回,并检测收敛。LLM从来不是自主的,它只提出查询。控制器强制执行边界、去重和停止条件。
协议: LLM必须输出JSON第一行: {"need_more": bool, "query": "...", "stop": bool},然后是他的回答。支持的协议: json (默认), regex, passive (单程,无精炼)。
停止条件:
llm_stop--LLM套件stop: truefixed_point--连续答案在阈值以上相似(默认值0.92)query_cycle--LLM重新请求已尝试的查询no_new_items--recall不会为建议的查询返回新项目max_calls--已达到迭代限制(默认值3)
旗帜:
| 标志 | 默认值 | 描述 |
|---|---|---|
--llm CMD | *(必填)* | LLM命令(例如。 "claude -p", "ollama run granite3.1:2b") |
--llm-mode | stdin | 如何传递提示: stdin 或 file |
--protocol | json | LLM输出协议: json, regex, passive |
--system-prompt | *(自动)* | 自定义系统提示(文本或文件路径) |
--max-calls | 3 | 最大LLM调用数 |
--threshold | 0.92 | 回答定点相似性阈值 |
--query-threshold | 0.90 | 查询周期相似性阈值 |
--stable-steps | 2 | 连续稳定的收敛步骤 |
--no-stop-on-no-new | off | 即使召回没有返回新项目,也要继续 |
--budget | 2200 | 上下文令牌预算 |
--trace | off | 向stderr发送JSONL跟踪 |
--trace-file | *(无)* | 将JSONL跟踪写入文件 |
--strict | off | 如果达到最大呼叫数而没有收敛,则退出1 |
--timeout | 300 | LLM子进程超时(秒) |
--replay FILE | *(无)* | 重播跟踪文件(无LLM调用) |
管道示例:
# Iterative recall with Claude
memctl push "How does authentication work?" --source docs/ \
| memctl loop "How does authentication work?" --llm "claude -p" --trace
# Sovereign local LLM
memctl push "database schema" --source src/ \
| memctl loop "database schema" --llm "ollama run granite3.1:2b" --protocol json
# Replay a trace (no LLM needed)
memctl loop --replay trace.jsonl "original question"memctl mount
memctl mount PATH [--name NAME] [--ignore PATTERN ...] [--lang HINT]
memctl mount --list
memctl mount --remove ID_OR_NAME将文件夹注册为结构化源。仅存储元数据——无扫描,无摄取。文件夹内容通过单独同步 sync 或自动通过 inspect.
memctl sync
memctl sync [PATH] [--full] [--json] [--quiet]Delta将装载的文件夹同步到内存存储中。使用3层增量规则:
- 新文件 (不在数据库中)→ 摄取
- 大小+时间匹配 → 快速跳过(无哈希)
- 哈希比较 → 仅在内容更改时才摄取
如果 PATH 如果已给出但尚未挂载,则首先自动注册。 --full 强制重新处理所有文件。
memctl inspect
# Orchestration mode — auto-mounts, auto-syncs, and inspects
memctl inspect PATH [--sync auto|always|never] [--no-sync] [--mount-mode persist|ephemeral]
[--budget N] [--ignore PATTERN ...] [--json] [--quiet]
# Classic mode — inspect an existing mount by ID/name
memctl inspect --mount ID_OR_NAME [--budget N] [--json] [--quiet]当给定一个位置时 PATH,检查操作 编排模式:
- 自动安装 --如果尚未装载,则注册该文件夹
- 稳定性检查 --将磁盘资源清册(路径/大小/mtime三元组)与存储进行比较
- 自动同步 --仅在过时(或始终/从不执行)时运行增量同步
--sync) - 检查 --生成确定性结构摘要
输出包括文件/块/大小总计、每个文件夹细分、每个扩展名分布、前5个最大文件和基于规则的观察结果。输出中的所有路径都是相对挂载的(绝不是绝对的)。
--mount-mode ephemeral 检查后删除挂载记录(保留语料库数据)。 --no-sync 是缩写 --sync never.
所有隐式操作(装载、同步)都在stderr上宣布。 --quiet 压制他们。
memctl ask
memctl ask PATH "question" --llm CMD [--inspect-cap N] [--budget N]
[--sync auto|always|never] [--no-sync] [--mount-mode persist|ephemeral]
[--protocol passive|json|regex] [--max-calls N] [--json] [--quiet]一次性文件夹Q&A。在一个命令中协调自动挂载、自动同步、结构检查、范围调用和有界循环。
| 标志 | 默认值 | 描述 |
|---|---|---|
--llm CMD | *(必填)* | LLM命令(例如。 "claude -p") |
--inspect-cap | 600 | 为结构上下文保留的令牌 |
--budget | 2200 | 代币总预算(检查+召回) |
--sync | auto | 同步模式: auto, always, never |
--no-sync | off | 跳过同步(简写为 --sync never) |
--mount-mode | persist | 保持安装(persist)或删除后(ephemeral) |
--protocol | passive | LLM输出协议 |
--max-calls | 1 | 最大循环迭代次数 |
预算拆分: --inspect-cap 标记转到结构上下文(文件夹树、观察)。其余部分(--budget 减 --inspect-cap)转到内容召回(FTS5结果作用于文件夹)。
召回范围: FTS结果经过后过滤,仅包括目标文件夹装载中的项目。其他支架上的物品不包括在内。
memctl chat
memctl chat --llm CMD [--session] [--store] [--folder PATH]
[--protocol passive|json|regex] [--max-calls N] [--budget N]
[--source FILE ...] [--quiet]交互式内存支持聊天REPL。每一轮:FTS5从内存中调用,向LLM发送上下文+问题,显示答案。持久读线历史(~/.local/share/memctl/chat_history)以及多行输入(发送空白行)。
默认情况下为无状态。 每个问题只看到记忆存储,没有隐藏的对话状态。
| 标志 | 默认值 | 描述 |
|---|---|---|
--llm CMD | *(必填)* | LLM命令(例如。 "claude -p", "ollama run granite3.1:2b") |
--protocol | passive | LLM输出协议。 passive =单程; json =迭代细化 |
--max-calls | 1 | 每圈最大循环迭代次数 |
--session | off | 启用内存会话上下文(最近问答的滑动窗口) |
--history-turns | 5 | 会话窗口大小(圈数) |
--session-budget | 4000 | 会话块字符限制 |
--store | off | 将每个答案作为STM项目保留 |
--source FILE... | *(无)* | 开始前预摄取文件 |
--folder PATH | *(无)* | 范围回调到文件夹(自动装载/同步) |
--tags | chat | 存储项的标签(逗号分隔) |
文件夹范围的聊天: --folder PATH 自动挂载和同步文件夹,然后将每次调用限制在该文件夹的项目上。结合了以下便利性 ask 随着互动 chat.
stdout纯度: 答案只会发送到stdout。提示、横幅和提示将转到stderr。
memctl export
memctl export [--tier T] [--type T] [--scope S] [--include-archived]将内存项作为JSONL(每行一个JSON对象)导出到stdout。每一行都是完整的 MemoryItem.to_dict() 序列化,包括完整的出处。
# Export all items
memctl export > backup.jsonl
# Export only LTM decisions
memctl export --tier ltm --type decision > decisions.jsonl
# Pipe between databases
memctl export --db project-a.db | memctl import --db project-b.dbstdout纯度: 只有JSONL数据会发送到stdout。进度转到stderr。
memctl import
memctl import [FILE] [--preserve-ids] [--dry-run]从JSONL文件或stdin导入内存项。每个项目都通过策略引擎。内容哈希重复数据消除可防止重复。
| 标志 | 默认值 | 描述 |
|---|---|---|
FILE | stdin | JSONL文件要导入 |
--preserve-ids | off | 保留原始项目ID(默认:生成新ID) |
--dry-run | off | 无需书写即可计数项目 |
# Import from file
memctl import backup.jsonl --db fresh.db
# Dry run — see what would happen
memctl import backup.jsonl --dry-run
# Preserve original IDs (for controlled migration)
memctl import backup.jsonl --preserve-ids --db replica.db______________________________________________________________________
配置
memctl读取可选 config.json 数据库旁的文件(自动检测)或显式文件 --config PATH 旗帜。
{
"store": {"fts_tokenizer": "fr"},
"inspect": {
"dominance_frac": 0.40,
"low_density_threshold": 0.10,
"ext_concentration_frac": 0.75,
"sparse_threshold": 1
},
"chat": {"history_max": 1000}
}优先: CLI --flag > MEMCTL_* 谁是 > config.json >编译默认值。配置文件丢失或无效将被自动忽略。
______________________________________________________________________
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
MEMCTL_DB | .memory/memory.db | SQLite数据库的路径 |
MEMCTL_BUDGET | 2200 | 注入区块的代币预算 |
MEMCTL_FTS | fr | FTS标记器预设(fr/en/raw) |
MEMCTL_TIER | stm | 默认写入层 |
MEMCTL_SESSION | *(未设置)* | 审核来源的会话ID |
优先: CLI --flag > MEMCTL_* 谁是 > config.json >编译默认值。总是。
______________________________________________________________________
退出代码
| 代码 | 含义 |
|---|---|
| 0 | 成功(包括幂等无运算) |
| 1 | 操作错误(参数错误、输入为空、策略拒绝) |
| 2 | 内部故障(意外异常、I/O错误) |
______________________________________________________________________
Shell 集成
添加 .bashrc, .zshrc,或您的项目 env.sh:
export MEMCTL_DB=.memory/memory.db
# Shortcuts
meminit() { memctl init "${1:-.memory}"; }
memq() { memctl push "$1"; } # recall only
memp() { memctl push "$1" ${2:+--source "$2"}; } # push with optional source
mempull() { memctl pull --tags "${1:-}" ${2:+--title "$2"}; }烟斗食谱
# Ingest docs + recall + feed to LLM + store output
memctl push "API design" --source docs/ | llm "Summarize" | memctl pull --tags api
# Search and pipe to jq
memctl search "auth" --json | jq '.[].title'
# Batch ingest a directory
memctl push "project overview" --source src/ tests/ docs/ -q
# Export all items as JSONL backup
memctl export > backup.jsonl
# Export only LTM items
memctl export --tier ltm > decisions.jsonl
# Import into a fresh database
memctl import backup.jsonl --db fresh.db
# Pipe between databases
memctl export --db project-a.db | memctl import --db project-b.db
# Dry-run import to check counts
memctl import backup.jsonl --dry-run
# Iterative recall-answer loop with trace
memctl push "auth flow" --source docs/ | memctl loop "auth flow" --llm "claude -p" --trace
# One-liner: inspect a folder (auto-mount + auto-sync)
memctl inspect docs/
# Inspect in JSON, pipe to jq for extension breakdown
memctl inspect src/ --json | jq '.extensions'
# Inspect without syncing (use cached state)
memctl inspect docs/ --no-sync --json
# One-shot folder Q&A (inspect + scoped recall + LLM)
memctl ask docs/ "What are the auth risks?" --llm "claude -p"
# Folder Q&A with JSON output
memctl ask src/ "Summarize the architecture" --llm "claude -p" --json
# Interactive folder-scoped chat
memctl chat --llm "claude -p" --folder docs/ --session --store
# Interactive chat with pre-ingested docs
memctl chat --llm "claude -p" --source docs/ --session --store______________________________________________________________________
MCP服务器
memctl公开了21个MCP工具,用于与Claude Code、Claude Desktop和任何兼容MCP的客户端集成。
快速安装
跨平台安装程序配置您的客户端,初始化工作区,并验证服务器是否启动:
# Claude Code (default) — cross-platform (Python)
memctl setup mcp
# Claude Desktop
memctl setup mcp --client claude-desktop
# Both clients, non-interactive
memctl setup mcp --client all --yes
# Custom database path
memctl setup mcp --db ~/my-project/.memory/memory.db
# Preview without changes
memctl setup mcp --dry-run遗留的Bash安装程序仍然可以通过 bash "$(memctl scripts-path)/install_mcp.sh".
安装程序:
- 验证Python 3.10+和
mcp套餐可用性 - 创建
~/.local/share/memctl/memory.db目录(如果缺失) - 插入/更新
memctl客户端MCP配置中的条目(带时间戳.bak备份) - 跑
memctl serve --check验证服务器是否启动 - 适用于pip、pipx和venv安装
支持的平台:macOS、Linux和Windows。
手动设置
如果您更喜欢手动配置:
# 1. Install
pip install "memctl[mcp]"
# 2. Initialize workspace
memctl init ~/.local/share/memctl
# 3. Verify
memctl serve --check --db ~/.local/share/memctl/memory.db然后添加到您的客户端配置中:
克劳德代码 (~/.claude/settings.json):
{
"mcpServers": {
"memctl": {
"command": "memctl",
"args": ["serve", "--db", "~/.local/share/memctl/memory.db"]
}
}
}克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上):
{
"mcpServers": {
"memctl": {
"command": "memctl",
"args": ["serve", "--db", "~/.local/share/memctl/memory.db"]
}
}
}启动服务器
memctl serve --db ~/.local/share/memctl/memory.db
# or
python -m memctl.mcp.server --db ~/.local/share/memctl/memory.db纵深防御(v0.8)
MCP服务器应用四层保护:
| 层 | 组件 | 用途 |
|---|---|---|
| 10个 | ServerGuard | 路径验证(--db-root),写入大小上限,导入批次限制 |
| L1级 | RateLimiter | 令牌桶限制:每会话20次写入/分钟,120次读取/分钟 |
| L1级 | SessionTracker | 内存会话状态,每圈写入跟踪 |
| L1级 | AuditLogger | 结构化JSONL审计跟踪(模式v1, rid 相关性) |
| 二级 | MemoryPolicy | 35种检测模式(秘密、注射、教学、PII) |
| 三级 | Claude代码挂钩 | 可选:PreToolUse安全防护+PostToolUse审计记录器 |
安全服务器示例:
# Default: db-root enforced, rate limits on, audit to stderr
memctl serve --db project/memory.db
# Explicit secure mode with audit file
memctl serve --db memory.db --db-root . --audit-log audit.jsonl
# Disable rate limits (development only)
memctl serve --db memory.db --no-rate-limit克劳德代码挂钩 (可选,与核心分开):
# Install safety guard + audit logger hooks (cross-platform)
memctl setup hooks
# Uninstall
memctl teardown hooksMCP工具
| 工具 | 描述 | 自 |
|---|---|---|
memory_recall | 令牌预算上下文注入(主要工具) | v0.1 |
memory_recall_best_effort | 使用级联跟踪的多步指导检索 | v0.19 |
memory_search | 交互式FTS5发现 | v0.1 |
memory_propose | 使用策略治理存储发现 | v0.1 |
memory_write | 直接写入(特权/dev,策略检查) | v0.1 |
memory_read | 按ID读取项目 | v0.1 |
memory_stats | 存储指标 | v0.1 |
memory_consolidate | 触发确定性合并 | v0.1 |
memory_mount | 注册、列出或删除文件夹装载 | v0.7 |
memory_sync | 同步装载的文件夹(增量或完整) | v0.7 |
memory_inspect | 来自语料库的结构注射块 | v0.7 |
memory_ask | 一次性文件夹问答 | v0.7 |
memory_export | 带过滤器的JSONL导出 | v0.7 |
memory_import | JSONL导入与策略执行 | v0.7 |
memory_loop | 有界召回应答循环 | v0.7 |
memory_reindex | 重建FTS5索引(标记器更改) | v0.12 |
memory_reset | 截断所有内存内容(已审核) | v0.13 |
memory_status | 项目内存运行状况仪表板 | v0.14 |
memory_diff | 比较两个项目或项目与修订版 | v0.15 |
memory_eco | 切换环保模式(开/关/状态) | v0.16 |
memory_promote | 将项目提升到更高级别 | v0.17 |
工具名称使用 memory_* 与RAGIX直接兼容的前缀。
Slash命令(生态模式,v0.13+)
eco模式安装了用于引导和高频操作的可选斜线命令:
| 命令 | 映射到 | 角色 |
|---|---|---|
/scan [path] | memory_inspect | Bootstrap--创建DB+索引 |
/recall | memory_recall | 搜索内存 |
/remember | memory_propose | 店铺观察 |
/reindex [preset] | memory_reindex | 重建FTS(先预览) |
/forget all | memory_reset | 重置内存(先预览) |
/consolidate | memory_consolidate | 合并相似项目(先预览) |
/status | memory_status | 项目内存运行状况仪表板 |
/export [--tier T] | memory_export | 将内存导出为JSONL |
/diff ID1 [ID2] | memory_diff | 比较项目或修订 |
Slash命令是 可选用户体验助手。所有功能仍然可用 通过CLI和MCP工具,无需安装任何slash命令。
生态模式(v0.9+)
使用克劳德代码? 请参阅 生态模式快速启动 对于一个动手 演练——安装、第一个会话、查询提示、工作流模式和故障排除。
克劳德本地人读取文件。eco-Claude质疑建筑。
生态模式用确定性结构检索取代了顺序文件浏览 以及持久的跨文件推理。手术块检索(精确算法,不是 文件头)、跨文件不变发现(测试中的架构)、有界成本 (代币减少约5倍)。
默认情况下,eco处于关闭状态。 它是可安装的,但在明确启用之前是禁用的。 这可以防止未经培训的用户出现“0结果”的第一印象问题。
一次性安装:
pip install "memctl[mcp]"
memctl setup eco --db-root .memory
memctl eco on # Enable eco mode (required)这设置了:
- 带项目范围内存的MCP服务器(
.memory/memory.db) - 生态提示钩 (
UserPromptSubmit)--注入具有项目计数、升级阶梯和检索/分析答案契约的规模感知上下文(约80个令牌/回合) - 生态轻推钩 (
PreToolUse,v0.18.2)-在索引项目上Grep/Glob之前的上下文提醒(>=200个项目,仅探索模式,从不阻止) - 战略文件(
.claude/eco/ECO.md)具有FTS5查询规则 - Slash命令:
/eco,/scan,/recall,/remember,/reindex,/forget,/consolidate,/status,/export,/diff
升级阶梯 (自v0.18.2起嵌入提示中):
memory_inspect--结构概述(文件树、大小、观察结果)memory_recall或/recall--选择性内容检索(FTS5,令牌预算,2-3个标识符)- 本土的
Grep/Glob--尽管查询经过优化,但只有在召回后返回0个结果 - 本土的
Read/View--用于编辑特定已知文件或行级精度
生态模式是对检索的建议,而不是对编辑的限制。 绕过eco用于:编辑文件、读取单个已知的小文件、git操作。
查询规范化(v0.10): 停用词(法语+英语文章、介词、, 在FTS搜索之前,问题词)会被自动删除。代码标识符 (CamelCase、snake_case、UPPER_case)始终保持不变。
FTS级联(v0.11+): 当多词查询返回0个结果时,系统 自动级联:AND→ 减少和→ 前缀\_ AND→ 或后退。前缀 扩展(v0.12)使用 "term"* 对于≥5个字符的术语,跳过波特词干。 每一步都会被记录下来,并制定相应的策略(fts_strategy)在MCP应答中报告。
阀杆(v0.12): memctl reindex --tokenizer en 启用波特词干 英语代码库。这 reindex 命令将元数据记录到 schema_meta 并发出 审计事件。使用 memctl stats 检查标记器和不匹配状态。
飞行员指导: 看 extras/eco/PILOT.md 对于通用 与开发团队(20-30名开发人员,2-4周, 指标、退出标准)。
演示: bash demos/eco_demo.sh --完整代码库上的4-act演示。
卸载:
memctl teardown eco
# Removes hook + strategy file. Preserves .memory/memory.db and MCP config.______________________________________________________________________
运作原理
建筑
memctl/
├── types.py Data model (MemoryItem, MemoryProposal, MemoryEvent, MemoryLink)
├── store.py SQLite + FTS5 + WAL backend (10 tables + schema_meta)
├── extract.py Text extraction (text files + binary format dispatch)
├── ingest.py Paragraph chunking, SHA-256 dedup, source resolution
├── policy.py Write governance (35 patterns: secrets, injection, instructional, PII)
├── config.py Dataclass configuration + JSON config loading
├── similarity.py Stdlib text similarity (Jaccard + SequenceMatcher)
├── loop.py Bounded recall-answer loop controller
├── mount.py Folder mount registration and management
├── sync.py Delta sync with 3-tier change detection
├── inspect.py Structural inspection and orchestration
├── chat.py Interactive chat REPL (readline history, multi-line)
├── ask.py One-shot folder Q&A orchestrator
├── query.py FTS query normalization and intent classification
├── export_import.py JSONL export/import with policy enforcement
├── cli.py 28 CLI commands
├── installer.py Cross-platform setup/teardown (MCP, eco, hooks)
├── consolidate.py Deterministic merge (Jaccard clustering, no LLM)
├── proposer.py LLM output parsing (delimiter + regex + JSON stdin)
└── mcp/
├── tools.py 21 MCP tools (memory_* prefix)
├── formatting.py Injection block format (format_version=1)
└── server.py FastMCP server entry point36个源文件。约14300行。核心的编译依赖项为零。
内存层
| 层次 | 目的 | 生命周期 |
|---|---|---|
| 短时记忆 (短期) | 最近的观察,未经证实的事实 | 由 pull.合并或过期。 |
| MTM (中期) | 经过验证、巩固的知识 | 由 consolidate。通过使用得到推广。 |
| 实验室用发射机模块 (长期) | 稳定的决策、定义、约束 | 根据使用次数或类型从MTM中推广。 |
策略引擎
每条写入路径都经过策略引擎。没有例外。
硬块 (拒绝):
- 10种秘密检测模式(API密钥、令牌、密码、私钥、JWT)
- 8种注射模式(提示覆盖、系统提示片段)
- 8种教学块模式(工具调用语法、角色片段)
- 超大内容(非指针类型超过2000个字符)
软积木 (隔离至STM,过期):
- 4种教学隔离模式(强制性自我指导)
- 5种PII模式(SSN、信用卡、电子邮件、电话、IBAN)
- 缺少来源或理由
- 隔离物品存放在
injectable=False
FTS5令牌化器预设
| 预设 | 标记器 | 用例 |
|---|---|---|
fr | unicode61 remove_diacritics 2 | 法语安全默认(口音规范化) |
en | porter unicode61 remove_diacritics 2 | 带波特词干的英语 |
raw | unicode61 | 不去除变音符号,不堵塞 |
专家覆盖: memctl init --fts-tokenizer "porter unicode61 remove_diacritics 2"
支持格式
| 类别 | 扩展 | 要求 |
|---|---|---|
| 文本/标记 | .md .txt .rst .csv .tsv .html .xml .json .yaml .toml | 无(stdlib) |
| 源代码 | .py .js .ts .jsx .tsx .java .go .rs .c .cpp .sh .sql .css … | 无(stdlib) |
| 办公文件 | .docx .odt | pip install memctl[docs] |
| 演示文稿 | .pptx .odp | pip install memctl[docs] |
| 电子表格 | .xlsx .ods | pip install memctl[docs] |
.pdf | pip install memctl[docs] (pypdf)或 pdftotext (poppler-utils) |
在分块和摄取之前,所有格式都被提取为纯文本。二进制格式库是延迟导入的——缺少库会产生清晰的 ImportError 安装说明。
内容寻址
每个摄入的文件都经过哈希处理(SHA-256)。重新摄取同一个文件是不允许的。每个内存项都存储一个 content_hash 用于重复数据删除。
整合
确定性,无LLM合并管道:
- 收集未存档的STM项目
- 按类型聚类+标签重叠(Jaccard相似性)
- 合并每个集群:最长的内容获胜;最早打破平局
created_at,然后是词典ID - 在MTM层写入合并项+
supersedes链接 - 存档原件(
archived=True) - 将高使用率的MTM项目推广到LTM
______________________________________________________________________
数据库模式
具有WAL模式的单个SQLite文件。10张桌子+1张FTS5虚拟桌子:
| 表 | 目的 |
|---|---|
memory_items | 核心内存项(22列) |
memory_revisions | 不可变修订历史 |
memory_events | 审计日志(每次读/写/合并) |
memory_links | 方向关系(取代、支持等) |
memory_embeddings | 保留给RAGIX(memctl中为空) |
corpus_hashes | SHA-256文件去重+挂载元数据(mount_id、rel_path、ext、size_bytes、mtime_epoch、lang_hint) |
corpus_metadata | 语料库级元数据 |
schema_meta | 架构版本、创建信息 |
memory_palace_locations | 保留给RAGIX |
memory_mounts | 已注册文件夹挂载(路径、名称、忽略模式、lang提示) |
memory_items_fts | 用于全文搜索的FTS5虚拟表 |
在中跟踪架构版本 schema_meta.当前: SCHEMA_VERSION=2从v1迁移是可加的(ALTER TABLE ADD COLUMN)和幂等的。
______________________________________________________________________
迁移到RAGIX
memctl提取自 拉吉克斯 并维护模式相同的数据库。要升级,请执行以下操作:
git clone git@github.com:ovitrac/RAGIX.git
cd RAGIX
pip install -e .[all]
# Point at the same database — all items carry over
ragix memory stats --db /path/to/your/.memory/memory.db| 功能 | memctl | RAGIX |
|---|---|---|
| SQLite模式 | 向前兼容(RAGIX可以打开memctl DB) | 超级集 |
| 注射格式 | format_version=1 | format_version=1 |
| MCP工具名称 | memory_* | memory_* |
| FTS5召回 | 是 | 是(+混合嵌入) |
| 文件夹装载+同步 | 是(v0.3+) | 否 |
| 嵌入 | 否 | 是(FAISS+Ollama) |
| LLM辅助合并 | 否 | 是 |
| 图表RAG | 否 | 是 |
| 报告 | 否 | 是 |
______________________________________________________________________
Python API
from memctl import MemoryStore, MemoryItem, MemoryPolicy
# Open or create a store
store = MemoryStore(db_path=".memory/memory.db")
# Write an item
item = MemoryItem(
title="Architecture decision",
content="We chose event sourcing for state management",
tier="stm",
type="decision",
tags=["architecture", "event-sourcing"],
)
store.write_item(item, reason="manual")
# Search
results = store.search_fulltext("event sourcing", limit=10)
for r in results:
print(f"[{r.tier}] {r.title}: {r.content[:80]}")
# Policy check
policy = MemoryPolicy()
from memctl.types import MemoryProposal
proposal = MemoryProposal(
title="Config", content="Some content",
why_store="Important finding",
provenance_hint={"source_kind": "doc", "source_id": "design.md"},
)
verdict = policy.evaluate_proposal(proposal)
print(verdict.action) # "accept", "quarantine", or "reject"
store.close()______________________________________________________________________
测试
pip install memctl[dev]
pytest tests/ -v对42个测试文件进行1204次测试,涵盖类型、存储、策略、摄取、文本提取、相似性、循环控制器、挂载、同步、检查、询问、聊天、导出/导入、配置、前向兼容性、合约、CLI(子流程)、管道组合、MCP工具、PII检测、配置验证、退出代码、查询规范化、注入完整性、模式分类、升级阶梯、提议者解析、生态模板、内存重置、钩子、环境诊断和策略性能。
______________________________________________________________________
文档
| 文档 | 描述 |
|---|---|
README.md | 此文件——概述、CLI参考、MCP服务器、体系结构 |
QUICKSTART.md | 一般快速入门:安装、第一内存、摄取、询问、MCP设置、常见问题 |
ECO_QUICKSTART.md | 克劳德代码的生态模式:第一次会话、查询提示、工作流模式、二进制格式 |
SECURITY.md | 安全策略、负责任的披露、威胁模型 |
CHANGELOG.md | 完整的发布历史记录(保持变更日志格式) |
extras/eco/ECO.md | 生态行为策略(安装在 .claude/eco/ECO.md) |
extras/eco/PILOT.md | 团队评估试点指导(20-30名开发人员,2-4周) |
extras/eco/README.md | 生态模式技术概述及安装参考 |
______________________________________________________________________
许可证
MIT许可证。看 许可证 了解详情。
______________________________________________________________________
作者 奥利维耶·维特拉克,博士,HDR| olivier.vitrac@adservio.fr |Adservio创新实验室
______________________________________________________________________
链接
- 仓库: https://github.com/ovitrac/memctl
- PyPI: https://pypi.org/project/memctl/
- 问题: https://github.com/ovitrac/memctl/issues
- 文档: DeepWiki
- 许可证: 麻省理工学院
______________________________________________________________________
*“每一行代码都应该有自己的位置。如有疑问,请将其排除在外。”*
