Token导航 LogoToken导航TokenDH.com
memctl (Ovitrac) logo
AI代理stdio官方级别未说明来源级核验

memctl (Ovitrac)

MCP Server

memctl是一个为LLM提供持久化、结构化内存的Unix原生内存控制平面,支持策略管理、零依赖和MCP原生。

工具数

21

提示词数

0

GitHub Stars

0

资源数

0
PythonClaude数据分析Claude DesktopClaude

安装说明

本站只整理中文说明和来源信息,不托管安装包,也不代用户安装。

作者 / 组织

ovitrac

提供方

ovitrac

最后核验

2026/5/17 20:23

快速接入

先看主来源和安装命令,再打开仓库或文档;下面只保留这个条目的关键接入事实。

命令预览

pip install memctl

详细介绍

memctl

一个文件,一个真相。为你的LLMs记忆。

用于LLM编排的Unix本机内存控制平面——零依赖、策略控制、MCP本机

![License: MIT](https://opensource.org/licenses/MIT) ![Python 3.10+](https://www.python.org/downloads/) ](https://github.com/ovitrac/memctl/releases) ![Tests](./tests) ![MCP](#mcp-server) ![DeepWiki](https://deepwiki.com/ovitrac/memctl) ![Code style: black](https://github.com/psf/black)

为什么选择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.db

2.摄入文件和召回

# 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 api

4.搜索

# Human-readable
memctl search "authentication"

# JSON for scripts
memctl search "database" --json -k 5

5.检查文件夹(单层)

# 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-sync

inspect 如果需要,自动挂载文件夹,检查过时性,仅在过时时进行同步,并生成结构化摘要。所有隐式操作都在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" --json

ask 将挂载、同步、结构检查和范围调用组合到一个命令中。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 CMDLLM的有界召回应答循环
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 PATHSQLite数据库路径
--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]

两相指令:

  1. 摄取 (可选):流程 --source 使用SHA-256去重和段落分块的文件。
  2. 召回: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: true
  • fixed_point --连续答案在阈值以上相似(默认值0.92)
  • query_cycle --LLM重新请求已尝试的查询
  • no_new_items --recall不会为建议的查询返回新项目
  • max_calls --已达到迭代限制(默认值3)

旗帜:

标志默认值描述
--llm CMD*(必填)*LLM命令(例如。 "claude -p", "ollama run granite3.1:2b")
--llm-modestdin如何传递提示: stdinfile
--protocoljsonLLM输出协议: json, regex, passive
--system-prompt*(自动)*自定义系统提示(文本或文件路径)
--max-calls3最大LLM调用数
--threshold0.92回答定点相似性阈值
--query-threshold0.90查询周期相似性阈值
--stable-steps2连续稳定的收敛步骤
--no-stop-on-no-newoff即使召回没有返回新项目,也要继续
--budget2200上下文令牌预算
--traceoff向stderr发送JSONL跟踪
--trace-file*(无)*将JSONL跟踪写入文件
--strictoff如果达到最大呼叫数而没有收敛,则退出1
--timeout300LLM子进程超时(秒)
--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层增量规则:

  1. 新文件 (不在数据库中)→ 摄取
  2. 大小+时间匹配 → 快速跳过(无哈希)
  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,检查操作 编排模式:

  1. 自动安装 --如果尚未装载,则注册该文件夹
  2. 稳定性检查 --将磁盘资源清册(路径/大小/mtime三元组)与存储进行比较
  3. 自动同步 --仅在过时(或始终/从不执行)时运行增量同步 --sync)
  4. 检查 --生成确定性结构摘要

输出包括文件/块/大小总计、每个文件夹细分、每个扩展名分布、前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-cap600为结构上下文保留的令牌
--budget2200代币总预算(检查+召回)
--syncauto同步模式: auto, always, never
--no-syncoff跳过同步(简写为 --sync never)
--mount-modepersist保持安装(persist)或删除后(ephemeral)
--protocolpassiveLLM输出协议
--max-calls1最大循环迭代次数

预算拆分: --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")
--protocolpassiveLLM输出协议。 passive =单程; json =迭代细化
--max-calls1每圈最大循环迭代次数
--sessionoff启用内存会话上下文(最近问答的滑动窗口)
--history-turns5会话窗口大小(圈数)
--session-budget4000会话块字符限制
--storeoff将每个答案作为STM项目保留
--source FILE...*(无)*开始前预摄取文件
--folder PATH*(无)*范围回调到文件夹(自动装载/同步)
--tagschat存储项的标签(逗号分隔)

文件夹范围的聊天: --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.db

stdout纯度: 只有JSONL数据会发送到stdout。进度转到stderr。

memctl import

memctl import [FILE] [--preserve-ids] [--dry-run]

从JSONL文件或stdin导入内存项。每个项目都通过策略引擎。内容哈希重复数据消除可防止重复。

标志默认值描述
FILEstdinJSONL文件要导入
--preserve-idsoff保留原始项目ID(默认:生成新ID)
--dry-runoff无需书写即可计数项目
# 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.dbSQLite数据库的路径
MEMCTL_BUDGET2200注入区块的代币预算
MEMCTL_FTSfrFTS标记器预设(fr/en/raw)
MEMCTL_TIERstm默认写入层
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 相关性)
二级MemoryPolicy35种检测模式(秘密、注射、教学、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 hooks

MCP工具

工具描述
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_importJSONL导入与策略执行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_inspectBootstrap--创建DB+索引
/recall memory_recall搜索内存
/remember memory_propose店铺观察
/reindex [preset]memory_reindex重建FTS(先预览)
/forget allmemory_reset重置内存(先预览)
/consolidatememory_consolidate合并相似项目(先预览)
/statusmemory_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起嵌入提示中):

  1. memory_inspect --结构概述(文件树、大小、观察结果)
  2. memory_recall/recall --选择性内容检索(FTS5,令牌预算,2-3个标识符)
  3. 本土的 Grep/Glob --尽管查询经过优化,但只有在召回后返回0个结果
  4. 本土的 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 point

36个源文件。约14300行。核心的编译依赖项为零。

内存层

层次目的生命周期
短时记忆 (短期)最近的观察,未经证实的事实pull.合并或过期。
MTM (中期)经过验证、巩固的知识consolidate。通过使用得到推广。
实验室用发射机模块 (长期)稳定的决策、定义、约束根据使用次数或类型从MTM中推广。

策略引擎

每条写入路径都经过策略引擎。没有例外。

硬块 (拒绝):

  • 10种秘密检测模式(API密钥、令牌、密码、私钥、JWT)
  • 8种注射模式(提示覆盖、系统提示片段)
  • 8种教学块模式(工具调用语法、角色片段)
  • 超大内容(非指针类型超过2000个字符)

软积木 (隔离至STM,过期):

  • 4种教学隔离模式(强制性自我指导)
  • 5种PII模式(SSN、信用卡、电子邮件、电话、IBAN)
  • 缺少来源或理由
  • 隔离物品存放在 injectable=False

FTS5令牌化器预设

预设标记器用例
frunicode61 remove_diacritics 2法语安全默认(口音规范化)
enporter unicode61 remove_diacritics 2带波特词干的英语
rawunicode61不去除变音符号,不堵塞

专家覆盖: 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 .odtpip install memctl[docs]
演示文稿.pptx .odppip install memctl[docs]
电子表格.xlsx .odspip install memctl[docs]
PDF.pdfpip install memctl[docs] (pypdf)或 pdftotext (poppler-utils)

在分块和摄取之前,所有格式都被提取为纯文本。二进制格式库是延迟导入的——缺少库会产生清晰的 ImportError 安装说明。

内容寻址

每个摄入的文件都经过哈希处理(SHA-256)。重新摄取同一个文件是不允许的。每个内存项都存储一个 content_hash 用于重复数据删除。

整合

确定性,无LLM合并管道:

  1. 收集未存档的STM项目
  2. 按类型聚类+标签重叠(Jaccard相似性)
  3. 合并每个集群:最长的内容获胜;最早打破平局 created_at,然后是词典ID
  4. 在MTM层写入合并项+ supersedes 链接
  5. 存档原件(archived=True)
  6. 将高使用率的MTM项目推广到LTM

______________________________________________________________________

数据库模式

具有WAL模式的单个SQLite文件。10张桌子+1张FTS5虚拟桌子:

目的
memory_items核心内存项(22列)
memory_revisions不可变修订历史
memory_events审计日志(每次读/写/合并)
memory_links方向关系(取代、支持等)
memory_embeddings保留给RAGIX(memctl中为空)
corpus_hashesSHA-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
功能memctlRAGIX
SQLite模式向前兼容(RAGIX可以打开memctl DB)超级集
注射格式format_version=1format_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
  • 许可证: 麻省理工学院

______________________________________________________________________

*“每一行代码都应该有自己的位置。如有疑问,请将其排除在外。”*

返回顶部

目录标签

目录标签

PythonClaude数据分析LLM内存管理本地部署SQLite存储策略管理Unix原生MCP集成

支持客户端

Claude DesktopClaude

接入字段

传输方式(transport,传输协议)

stdio

鉴权方式(authType,认证方式)

session

工具数量(toolCount,工具数)

21

资源数量(resourceCount,资源数)

0

提示词数量(promptCount,提示词数)

0

权限和风险

stdiosession部署方式未说明

接入前请确认传输方式、认证方式和部署位置,并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限;先核对安装命令和配置内容。

来源信息

继续浏览同类 MCP