LLMSlim memory

## 30 秒内即可使用

下面的每种 MCP 配置都会通过 uv（Python 3.10 或更高版本）启动同一个服务 llmslim mcp。记忆会保存到本地 SQLite 文件 ~/.llmslim/memory.db。

一键安装：

工具	运行方式
Claude Code	claude mcp add llmslim -- uvx --from "llmslim[mcp]" llmslim mcp
Claude Code 插件	/plugin marketplace add Thanatos9404/llmslim，然后运行 /plugin install llmslim@llmslim
Codex	codex mcp add llmslim -- uvx --from "llmslim[mcp]" llmslim mcp
GitHub Copilot CLI	copilot mcp add llmslim -- uvx --from "llmslim[mcp]" llmslim mcp
Gemini CLI	gemini extensions install https://github.com/Thanatos9404/llmslim
Hermes Agent	hermes plugins install llmslim --enable，然后运行 hermes config set context.engine llmslim：一个可在本地精简长对话的上下文引擎（插件）

首次启动时会下载 LLMSlim 及其依赖。如果客户端等待超时，请先运行一次 uvx --from "llmslim[mcp]" llmslim mcp --help，以填充 uv 的缓存，然后重启客户端。

Python（pip install llmslim，Python 3.9 或更高版本）：

from llmslim.memory import Memory

mem = Memory("memory.db")  # a SQLite file; Memory("postgresql://...") with llmslim[postgres]
mem.add([{"role": "user", "content": "I'm allergic to peanuts."}], user_id="asha")
context = mem.search("Am I allergic to anything?", user_id="asha", budget=1500)
print(context.text)  # put it in your prompt as data, not instructions

TypeScript（npm install llmslim，Node 18 或更高版本），连接到 llmslim serve（pip install "llmslim[server]"）：

import { LLMSlim } from "llmslim";

const slim = new LLMSlim(); // http://127.0.0.1:8080 unless LLMSLIM_BASE_URL is set
await slim.memories.add({ userId: "asha", messages: "I'm allergic to peanuts." });
const context = await slim.memories.search({ userId: "asha", query: "Am I allergic to anything?", budget: 1500 });

可运行示例，每个示例均附带测试：Claude Code 记忆、LangChain Agent、Pydantic AI Agent、大型日志和 TypeScript。

如果 LLMSlim 对你有帮助，请点个 star，让更多人发现它。欢迎在 issues 中反馈。

功能

• 五种 MCP 工具： remember、recall、list_memories、forget 和 fit_context。
• 逐字存储消息到 SQLite 或 Postgres。写入时不会进行摘要或提取。
• 在令牌预算内回忆内容。 recall 会返回能够回答问题的已存储消息，附带日期，并在预算允许的范围内保留完整内容。fit_context 会将长日志或文档压缩到指定预算内。
• 在服务启动时固定作用范围。 用户和 Agent ID 在服务启动时设置，而不是由模型设置，因此，受注入文本操控的模型无法读取或删除其他用户的记忆。
• 不会调用大模型。 默认情况下，存储和回忆均由纯代码完成：不需要模型、嵌入 API 或 API 密钥。
• 采用 MIT 许可。 该库需要 Python 3.9 或更高版本，MCP 服务需要 Python 3.10 或更高版本。

除了记忆功能外，LLMSlim Core 还会将提示词、聊天历史、检索到的文档和工具架构压缩并规划到令牌预算内：请参阅下文各章节。

为什么不调用大模型

存储只是写入数据库，回忆则使用确定性的排序代码。因此，返回的内容就是当时说过的话，而非模型改写后的内容；相同的历史和问题始终会得到相同的上下文，这让回忆功能易于测试。记忆服务和 llmslim serve 本身不会发起网络调用。会访问网络的操作包括：从 PyPI 安装（包括 uvx 首次运行某个版本）以及 tiktoken 首次下载其分词器文件。

取舍在于：默认的词法模式匹配的是词语，而非含义，因此，如果问题的表述与已存储消息不同，可能无法匹配到相关内容。relevance="semantic" 可为此添加可选的交叉编码器（llmslim[semantic]，首次使用时会下载模型）。请参阅限制。

---

60 秒压缩提示词

1. 安装 PyPI 上的 LLMSlim Core（Python 3.9+）。运行时无需 API 密钥、模型或网络调用：

pip install llmslim

2. 运行此代码片段：

from llmslim import compress

ticket = """
Hi team, I hope you are all doing well and had a good weekend.
I am writing about invoice INV-2291, which charged us $480 instead of $240.
We upgraded to the Pro plan on 3 September, but the old Basic plan was billed as well.
Our finance lead was asking about this during the weekly sync, which ran long as usual.
Please refund the duplicate $240 charge to the card ending 4417.
Thanks so much, and let me know if you need anything else from me.
"""

result = compress(ticket, target_ratio=0.6)  # target: keep about 60% of the tokens
print(result.compressed_text)
print(f"{result.original_tokens} -> {result.compressed_tokens} tokens ({result.reduction_percent:.1f}% fewer)")

3. 预期结果（llmslim 0.11.1，基础安装）：

Hi team, I hope you are all doing well and had a good weekend. I am writing about invoice INV-2291, which charged us $480 instead of $240. We upgraded to the Pro plan on 3 September, but the old Basic plan was billed as well. Please refund the duplicate $240 charge to the card ending 4417.
112 -> 72 tokens (35.7% fewer)

六个句子中有两个会被删去；发票编号、金额、套餐变更和退款请求都会保留。默认的抽取式模式只会从输入中选取句子，因此相同的输入始终会得到相同的输出。基础安装会按每个令牌约 4 个字符估算令牌数，并打印一行警告说明这一点。使用 pip install "llmslim[fast-tokens]" 后，则会改用 tiktoken 统计令牌数：对于此输入，同样会保留这四个句子，计数结果为 107 -> 72 tokens (32.7% fewer)。

下一步：文档 • 平台测试版 • 问题反馈

---

LLMSlim Core 和 LLMSlim Platform

面向生产级 AI Agent 的上下文层。 此仓库是 LLMSlim Core（v0.11.2，MIT）：一种本地优先的上下文规划与压缩方案，可将提示词、对话历史、RAG、记忆和工具架构纳入实际 token 预算，同时保留指令和执行边界。

	LLMSlim Core	LLMSlim Platform
版本	0.11.2	0.9.1 beta
许可证	MIT，本仓库	专有，私有 beta
安装	pip install llmslim	受邀使用；未发布到 PyPI
功能	在 Python 进程中压缩、规划并追踪模型可见的上下文	基于 Core 构建：提供可验证的 Agent 状态时间线、可解释且可重放的上下文决策，以及从影子模式开始、由结果驱动的上下文策略

Core 始终完全开源。Platform 是依赖 Core 的独立产品；其代码均不在本仓库中。请访问 llmslim.app/platform 了解详情并申请 beta 访问权限。

Core 最新内容：Agent 上下文运行时（v0.7.0） 和缓存感知上下文运行时（v0.7.1）。 两者自 0.7.1 起均包含在 PyPI 软件包中；0.7.0 已打标签，但未发布到 PyPI。

---

自适应上下文规划器（v0.6.0）

LLMSlim 不再只是固定比例的提示词压缩器。自适应 上下文规划器会为每个上下文项选择安全的表示方式，然后使用 确定性的受约束分配器，将价值最高的上下文纳入有限的模型预算。 原有的 compress() API 仍完全受支持。

v0.6.0 版本新增了可解释的逐项决策、明确的不可行性报告、 规划后验证、token 和成本遥测、策略预设，以及可选的 Sarvam AI、Zoho 和 MongoDB 集成，同时保持基础安装本地优先且不绑定服务提供商。

from llmslim import plan_context

plan = plan_context(
    messages=[
        {"role": "system", "content": "Answer only from verified context."},
        {"role": "user", "content": "When does Acme renew?"},
    ],
    documents=[{"content": "CRM: Acme renews on 2026-11-30."}],
    query="Acme renewal date",
    model="sarvam-105b",
    max_input_tokens=8_000,
    reserve_output_tokens=512,
)
assert plan.feasible
print(plan.final_context)
print(plan.metrics.planned_tokens, plan.metrics.estimated_input_cost_after)

基础安装即可离线规划。可选集成通过额外组件隔离：

pip install "llmslim[sarvam]"   # Sarvam provider (official sarvamai SDK)
pip install "llmslim[zoho]"     # CRM and WorkDrive context sources
pip install "llmslim[mongodb]"  # explicit memory and Atlas retrieval

请参阅架构、 算法、安全模型、 CLI和实测离线基准。

---

初创企业计划

LLMSlim 属于 15 个初创企业计划。这些计划提供额度、工具和指导； 它们都不是投资方，加入计划也不代表获得认可。

计划	公司
Sarvam Startup Program	Sarvam AI
Zoho for Startups	Zoho
MongoDB for Startups	MongoDB
Claude for Startups	Anthropic
OpenAI for Startups	OpenAI
Auth0 for Startups	Okta (Auth0)
Zendesk for Startups	Zendesk
Mixpanel for Startups	Mixpanel
Sentry for Startups	Sentry
Descope Hello World Startup Program	Descope
Pulumi for Startups	Pulumi
Honeycomb for Builders	Honeycomb
Exa Startup Grants	Exa
Neo4j Startup Program	Neo4j
Cartesia Startups Grant Program	Cartesia

Logo 是其所有者的商标，用于标识各项计划。

---

Sarvam Startup Program 和 Sarvam 集成

✦ 已获 Sarvam Startup Program 接纳

LLMSlim 已获 Sarvam Startup Program 接纳。这仅代表加入了该计划：这并非合作关系，也不代表获得 Sarvam AI 的认可。

此外，LLMSlim Core 提供可选的 Sarvam 集成（llmslim[sarvam]），基于官方 sarvamai Python SDK 构建。你可以在本地规划并压缩上下文，然后仅将规划后的上下文发送给 Sarvam 模型，例如 sarvam-105b。

• 本地规划：在发送任何请求之前，检索到的文档会在你的 Python 进程中完成规划和压缩。
• 本地优先：敏感的检索上下文保留在本地；只有规划后的上下文会发送给模型。
• 应用由你掌控：LLMSlim 是一个预处理器。你的应用负责 API 密钥、提示词和推理；除非你的代码调用该提供方，否则不会向 Sarvam 发送任何内容。

快速入门：自适应规划 + Sarvam

pip install "llmslim[sarvam]"
export SARVAM_API_KEY="..."   # your own Sarvam API key

from llmslim import plan_context
from llmslim.integrations.sarvam import SarvamProvider

documents = [
    {"content": "Q3 filing: new data-localisation rules take effect in April 2027."},
    {"content": "Q3 filing: two pending licence renewals carry a regulatory risk of delay."},
]

plan = plan_context(
    messages=[{"role": "system", "content": "Answer from verified context."}],
    documents=documents,
    query="Summarize the key regulatory risks.",
    model="sarvam-105b",
    max_input_tokens=8_000,
    reserve_output_tokens=256,
)
provider = SarvamProvider.from_env(model="sarvam-105b", max_tokens=256)
answer = provider.chat([{"role": "user", "content": plan.final_context}])
print(answer, provider.last_usage)

👉 阅读 Sarvam 集成指南（也可参阅 docs/integrations/SARVAM.md）

---

🔮 什么是 LLMSlim？

现代大模型系统面临上下文窗口困境：

1. 成本负担：每轮都重新发送长提示词，意味着你要一遍又一遍地为相同的输入 token 付费。
2. 延迟瓶颈：长提示词会增加首 token 时间（TTFT）和排队时间。
3. 中间信息丢失综合征：模型可能会漏掉或误用埋在长上下文中间的信息。
4. 安全风险：不可信的 RAG 内容可能将间接提示词注入夹带进系统指令。

**LLMSlim 从源头解决这一问题。**它提供确定性的、保留契约的压缩，并在调用任何模型之前直接在你的应用层运行。

💎 核心架构支柱

支柱	LLMSlim 如何解决
🏎️ 超低开销	纯 Python + NumPy/Scikit-learn。在包含 24 个样本、以短文本为主的 Phase 2 评估中，每个样本的中位耗时为 0.026 ms（p95 为 1.889 ms），默认路径不会调用模型。输入越长，耗时越久。
🔒 默认确定性	默认的抽取模式只会从输入中选取句子，因此输出可复现，且不包含生成文本。但它仍可能删掉你需要的事实，因此请针对你的使用场景检查结果。改写和混合模式会调用你自己的 LLM。
🛡️ 来源安全性	ContextRole 层级会隔离不可信的 RAG/工具文本，防止提示词注入提升到 system 优先级。
🧩 符合契约的工具模式	规范化 JSON、SHA-256 契约指纹，以及面向 Agent 工具的零执行改写。
🔌 与提供方无关	为 Sarvam、OpenAI、Anthropic、Gemini 和 vLLM 提供不执行请求的构建器，并提供 OpenAI Agents SDK 桥接。适用于任何能传递纯消息列表或文档列表的框架。

---

🖥️ 在线 Studio Playground（www.llmslim.app）

粘贴一段长聊天记录、一组搜索结果或一份 CI 日志，提出问题，然后观察 LLMSlim 如何保留能够回答问题的内容。Studio 会显示节省的 token 数和成本、答案是否得以保留，以及如果按相同长度进行纯截断，原本会保留哪些内容。

• 现成场景： 一段为期六个月的支持聊天记录、帮助中心搜索结果，以及一份包含一处故障的 CI 日志；每个场景都附有一个答案已知的问题。
• 使用自己的文本： 粘贴最多约 16,000 个 token 的文本，并选择保留量。
• 原文内查看： 在原文中高亮显示保留的行，旁边展示模型实际会收到的精确文本。
• 不调用模型： Studio 在服务器上运行 Core，不会调用任何提供方。你粘贴的内容不会被存储。

请参阅 Studio 部署和安全策略。

👉 打开交互式 Studio

---

🌐 现代化开发者网站与文档

探索我们重新设计的深色／浅色文档网站，了解端到端集成模式：

---

📦 安装

# Core package (Deterministic extractive engine, 0 external LLM dependencies)
pip install llmslim

# With optional Model Context Protocol (MCP) catalog ingestion (Python 3.10+)
pip install "llmslim[mcp]"

# With optional OpenAI Agents SDK host bridge (Python 3.10+)
pip install "llmslim[agents]"

# With optional local multilingual semantic retrieval
pip install "llmslim[semantic]"

# Sarvam: chat providers, language tools and document source (official sarvamai SDK)
pip install "llmslim[sarvam]"

# Exa web search as an untrusted RAG context source (spend capped in USD)
pip install "llmslim[exa]"

# Neo4j temporal agent memory with auditable supersession
pip install "llmslim[neo4j]"

# Read-only Zoho CRM and WorkDrive context sources
pip install "llmslim[zoho]"

# Explicit MongoDB context memory and Atlas retrieval
pip install "llmslim[mongodb]"

# LangChain, LlamaIndex (Python 3.10+) and Haystack adapters
pip install "llmslim[langchain]"
pip install "llmslim[llamaindex]"
pip install "llmslim[haystack]"

# Agent history: gptme (0.34+) and Pydantic AI adapters (Python 3.10+).
# Hermes Agent needs no extra: install llmslim into Hermes's environment.
pip install "llmslim[gptme]"
pip install "llmslim[pydantic-ai]"

# All optional extensions
pip install "llmslim[all]"

要求：Python 3.9 或更高版本。默认安装无需提供方 SDK、PyTorch、sentence-transformers 或云服务。

---

⚡ 快速开始与使用模式

1. 基本抽取式压缩（默认）

from llmslim import ContextRole, compress

text = """
The Apollo program was conceived in 1960 during the Eisenhower administration.
NASA announced the program as a follow-up to Project Mercury.
The spacecraft was designed to carry three astronauts.
Apollo succeeded in landing the first humans on the Moon in 1969.
Funding for the program peaked in 1966 with over $4.5 billion appropriated.
"""

result = compress(
    text,
    target_ratio=0.5,                    # Target: keep about 50% of the tokens
    strategy="extractive",               # Deterministic sentence selection
    context_role=ContextRole.GENERAL,
)

print("Compressed Output:")
print(result.compressed_text)
print(f"Original: {result.original_tokens} tokens | Compressed: {result.compressed_tokens} tokens")
print(f"Saved: {result.tokens_saved} tokens ({result.reduction_percent:.1f}%)")
print(f"Sentences kept: {result.sentences_kept} of {result.sentences_total}")

抽取式选择保留完整句子，而非句意：请务必检查你需要的句子是否得以保留。对于这段文本，0.7.1 基础安装会保留五个句子中的三个，并删掉 1969 年登月的句子；使用 llmslim[fast-tokens]（通过 tiktoken 计数）时，则会保留该句子并删掉另一个句子。

---

2. 多文档 RAG 压缩

构建提示词前，先压缩每个检索到的文本块。compress_documents 接收纯文本字符串，并按顺序为每份文档返回一个结果：

from llmslim import compress_documents

documents = [
    "Q3 revenue grew 23% year-over-year to $1.2B. "
    "Growth came mainly from enterprise subscriptions in India and Southeast Asia. "
    "The board met twice during the quarter. "
    "The office cafeteria menu was updated in August. "
    "A new logo was unveiled at the annual offsite. "
    "Net revenue retention reached 118%, up from 109% a year earlier.",
    "Operating expenses rose 11% because of AI research infrastructure. "
    "Most of the increase was GPU capacity for model evaluation. "
    "Travel costs were flat. "
    "The parking garage was repainted in September. "
    "Employees voted on a new name for the meeting rooms. "
    "Headcount in engineering grew by 40 people.",
]

results = compress_documents(
    documents,
    query="What drove Q3 revenue and cost changes?",
    target_ratio=0.5,
)

context = "\n\n".join(r.compressed_text for r in results)
print(context)
print(f"Saved {sum(r.tokens_saved for r in results)} tokens across {len(results)} documents")

使用查询时，所有文档共享同一预算，预算会分配给与查询相关的内容。默认使用词法相关性 （带反馈的 BM25：无需模型、结果确定，在 3k-token 上下文中耗时数十毫秒）。对于 RAG 和长聊天 记忆，答案与问题往往只有少量共同词语，可添加可选的重排序器：

# pip install "llmslim[semantic]"   (sentence-transformers; uses a GPU when there is one)
results = compress_documents(documents, query=question, target_ratio=0.25, relevance="semantic")

relevance 也接受任意可调用的 scorer(query, texts) -> scores，例如托管式重排序 API。

使用 LangChain、LlamaIndex 或 Haystack 检索？请改用 框架适配器，而不是自行调用 compress_documents。

说明

默认情况下，compress_documents 会将文档视为不可信内容（ContextRole.RAG）， 因此，检索到的文档中的祈使措辞绝不会被强制保留为受保护的指令。它不会移除注入文本：注入的句子 仍可能在压缩后保留。若要在最终提示词中将检索到的内容标记为不可信，请使用 plan_context 或 ContextRuntime，它们会为每份文档添加 trusted="false" 来源标签，并忽略文档对自身角色的声明。

---

3. 多轮聊天对话压缩

压缩较早的长轮次，同时原样传递 system 指令和用户问题：

from llmslim import compress_chat_messages

review = (
    "Here are my suggestions for your schema. First, add a composite index on "
    "(customer_id, created_at) because most of your queries filter by customer and sort by "
    "date. Second, the orders table stores the shipping address inline, which duplicates "
    "data across rows; move it to an addresses table. Third, the status column is a "
    "free-text string, so use an enum or a lookup table instead. Fourth, the price column "
    "uses FLOAT, which loses precision for money; use DECIMAL(12, 2). Finally, add ON "
    "DELETE RESTRICT to the foreign key from orders to customers so that deleting a "
    "customer cannot silently orphan their orders."
)

messages = [
    {"role": "system", "content": "You are a specialized code review engineer."},
    {"role": "user", "content": "Can you review my database schema design?"},
    {"role": "assistant", "content": review},
    {"role": "user", "content": "What about the foreign key constraint on line 42?"},
]

compressed_messages = compress_chat_messages(
    messages,
    target_ratio=0.5,
    compressible_roles=("assistant",),  # Only compress assistant turns; system and user pass through
    min_tokens=60,                      # Turns shorter than this are never compressed
)

for message in compressed_messages:
    print(f"{message['role']}: {message['content']}")

---

4. 混合提示词优化（抽取 + 改写）

将超快速的抽取式预过滤与您自己的大模型服务商结合，实现深入的语义改写：

from llmslim import CallableProvider, compress
import openai

client = openai.OpenAI()  # reads OPENAI_API_KEY; requires `pip install openai`

long_raw_text = """
The Apollo program was conceived in 1960 during the Eisenhower administration.
NASA announced the program as a follow-up to Project Mercury.
The spacecraft was designed to carry three astronauts.
Apollo succeeded in landing the first humans on the Moon in 1969.
Funding for the program peaked in 1966 with over $4.5 billion appropriated.
"""

# Define your own provider callback (LLMSlim does not bundle vendor SDKs).
# The callback receives a RewriteRequest with ready-made prompts and returns text.
provider = CallableProvider(
    lambda req: client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": req.system_prompt},
            {"role": "user", "content": req.user_prompt},
        ],
    ).choices[0].message.content
)

result = compress(
    long_raw_text,
    target_ratio=0.3,
    strategy="hybrid",                   # 1. Extractive filter -> 2. LLM semantic rewrite
    provider=provider,
)

meta = result.rewrite_metadata
print(result.compressed_text)
print(f"Strategy: {meta.strategy} | Rewrite accepted: {meta.accepted} | Fell back to extractive: {meta.fallback_used}")
print("Validation failures:", meta.failure_reasons)

每次改写都会针对结构、指令保留、实体保留和相似度进行验证。如果混合改写未通过验证，LLMSlim 会返回 抽取式结果，并在 rewrite_metadata.failure_reasons 中说明原因。

---

编码 Agent：llmslim wrap claude

Claude Code 每轮都会重新发送完整对话。因此，冗长的测试日志、构建输出、搜索结果和网页内容会被反复计费，并不断增加 Claude Code 最终需要压缩的上下文。

llmslim wrap claude 通过本地代理运行 Claude Code：

• 模型第一次看到这类输出时，会对其进行精简。看起来像错误、失败或警告的行会排在前面，其次是与命令相关的行。
• 后续每次请求都会发送完全相同的字节，因此提示词缓存会持续命中，Claude 的思考也能保持有效。
• Claude Code 自带的 Read、Edit 和 Write 工具的输出不会被触碰。通过 shell 打印的文件（cat、head）则算作 shell 输出。

pip install "llmslim[proxy]"
llmslim wrap claude
llmslim proxy stats

实测账单影响：在真实的 Claude Code 2.1.296 和 Claude Haiku 5.5 上，对八个小型合成任务进行了测量。我们根据 API 用量按标价计算费用，并单独计算缓存读取的费用；所有 572 次运行均已发布在 benchmarks/claude_code_cost 中。主要结果的两组测试都使用 Claude Code 默认权限模式；另一次运行的两组测试都使用自动模式。

• **长日志：**模拟的 CI 运行失败（日志约 12 KB，原因位于中间）费用降低了 26-32%；包含 240 条警告和 3 个错误的 lint 运行费用降低了 17-21%。
• **测试运行：**默认模式下费用降低约 4%，所有任务的结果都处于噪声范围内；自动模式下降低了 2-15%。Agent 本来就会用 tail 精简测试输出。
• **8 个任务总体：**默认模式下费用增加了 5.3%（95% 区间为 +1.5% 至 +9.4%），主要是因为某个任务的缩短版 JSON 费用约为原来的两倍；自动模式下费用降低了 5.1%。从 0.11.1 起，默认不会处理 JSON。
• **真实会话：**在对维护者自己的对话记录进行离线重放时（32 个会话及其启动的 412 次子 Agent 运行，几乎都使用 Claude Opus 5.5，按标价计算），工具输出在账单中占比较小：若保持轮次不变，并假设所有 shell、搜索和网页输出都不收费，费用会降低 13.4%。重新读取长上下文才是主要开销。Claude Code 的 /autocompact 设置决定何时进行压缩；本文未测量其对费用的影响。

如果不逐字节重放，经过编辑的历史记录会让 Claude 的思考失效：在我们对 Claude Haiku 5.5 的 API 检查中，请求被拒绝并返回 HTTP 400；对于 2026 年 8 月 31 日或之后创建的账户，这是默认行为。使用重放后，一项包含 7 个请求的 API 测试中，每次请求的缓存读取量都在增加。有关压缩内容、限制和安全性的说明，请参阅 docs/PROXY.md。

**作为 Claude Code 插件。**该插件会添加 LLMSlim 的记忆服务（见下文）和两个命令：

• /llmslim:wrap-claude 会引导你通过代理启动 Claude Code；
• /llmslim:savings 会显示代理为你的请求省去了多少工具输出 token：这是提示词缓存折扣前的估算值，并非节省的金额。

/plugin marketplace add Thanatos9404/llmslim
/plugin install llmslim@llmslim

在 Claude Code 2.1.275 或更高版本中，运行 /plugin install llmslim --marketplace Thanatos9404/llmslim 即可一步完成上述操作。 记忆服务通过 uvx 运行，因此需要安装 uv。

为 Agent 提供记忆，无需 LLM 参与

llmslim.memory 会逐字存储每一轮对话，并在读取时从中挑选出能在 token 预算内回答问题的轮次。写入时不会使用抽取模型，读取时也不会调用模型。

from llmslim.memory import Memory

memory = Memory("memory.db")  # SQLite, built into Python
memory.add([{"role": "user", "content": "I'm allergic to peanuts."}], user_id="asha")
context = memory.search("Am I allergic to anything?", user_id="asha", budget=1500)
print(context.text)  # put it in the prompt as untrusted data

它运行的是 round-3 基准测试背后的流程。在 Mem0 自己的 LongMemEval 问题集上，该流程（使用其重排器）答对率为 78.3%，每 1,000 个问题费用为 $1.04；Mem0 的答对率为 76.7%，费用为 $220.88。若要从 Mem0 迁移，from llmslim.memory.compat import Mem0Memory as Memory 可保留 Mem0 的方法名称。有关作用域、存储、证据和限制，请参阅 docs/MEMORY.md 及 1.0 路线图。

在 Claude、Cursor 或任何 MCP 客户端中

llmslim mcp 通过 MCP 提供此记忆，并为长文本提供 fit_context 工具。它需要在 Python 3.10+ 上运行 pip install "llmslim[mcp]" 进行安装。

claude mcp add llmslim -- llmslim mcp

• 工具： remember、recall、list_memories、forget 和 fit_context。
• 范围： 服务通过 --user-id 固定用户，因此模型无法读取其他用户的记忆。
• 存储： 本地 SQLite 文件；服务本身不会发起网络调用（分词器只会下载一次文件并将其缓存）。
• 更多信息： 客户端配置和选项见 docs/MCP.md。

在其他客户端中一键安装。每个链接都会运行 uvx --from "llmslim[mcp]==0.11.2" llmslim mcp，因此需要安装 uv 和 Python 3.10 或更高版本。

在 Gemini CLI 中，运行 gemini extensions install https://github.com/Thanatos9404/llmslim 即可添加同一服务。 在 VS Code 中，LLMSlim Memory 扩展会将其添加到 VS Code 的 MCP 支持中（即将登陆 VS Code Marketplace 和 Open VSX）。

通过 HTTP 从任何语言调用

llmslim serve 会通过一个简洁的 JSON API 提供同一套记忆和上下文适配端点。它以单个进程运行，使用一个 SQLite 文件，且不会调用模型。可通过 pip install "llmslim[server]" 安装，或构建 Dockerfile。

curl -s localhost:8080/v1/memories/search -H 'content-type: application/json'   -d '{"user_id": "asha", "query": "Where did I move to?", "budget": 1500}'

如果要在 localhost 之外监听，则需要 bearer API 密钥。路由、限制和 Docker 设置见 docs/SERVER.md。

TypeScript 客户端 npm install llmslim（clients/typescript）可无依赖地封装此 API。它还为 Vercel AI SDK 提供 recall_memory 和 remember 工具，以及用于保存对话轮次的中间件。它们都不会更改你的提示词，因此提示词缓存仍能命中，Claude 保留的思考也依然有效。

与 LangChain / LlamaIndex / Haystack 搭配使用

每个适配器都会对检索到的文档运行 compress_documents，有查询时使用相同的共享预算。保留的文档会保留其元数据，压缩为空的文档则会被丢弃。它们在本地运行，不使用模型。

框架	安装	类	用法
LangChain	llmslim[langchain]	llmslim.integrations.langchain.LLMSlimCompressor	用于原本会使用 LLMLinguaCompressor 的地方，例如 ContextualCompressionRetriever
LlamaIndex	llmslim[llamaindex]（Python 3.10+）	llmslim.integrations.llama_index.LLMSlimPostprocessor	用于原本会使用 LongLLMLinguaPostprocessor 的地方，置于 node_postprocessors 中
Haystack	llmslim[haystack]	llmslim.integrations.haystack.LLMSlimDocumentCompressor	作为检索器与提示词构建器之间的组件

from langchain_classic.retrievers.contextual_compression import ContextualCompressionRetriever
from llmslim.integrations.langchain import LLMSlimCompressor

retriever = ContextualCompressionRetriever(
    base_compressor=LLMSlimCompressor(target_ratio=0.25),
    base_retriever=your_retriever,
)

可运行示例及其输出： LangChain、 LlamaIndex、 Haystack。

---

与 gptme / Hermes Agent / Pydantic AI 搭配使用

这些适配器会将 Agent 的消息历史压缩至令牌预算内。它们会原样保留系统提示词、工具调用和最新轮次，在本地压缩较早的工具输出和轮次（工具输出中的失败信息和回溯会予以保留），并确保每个工具调用都与其结果配对。不会调用模型。

Agent	安装	类或函数	接入方式
gptme	llmslim[gptme]（gptme 0.34+）	llmslim.integrations.gptme.LLMSlimContextProvider	gptme 上下文提供器 llmslim；设置 [plugin.llmslim] compaction = true 后，gptme 的压缩功能会使用它
Hermes Agent	Hermes 环境中的 llmslim	llmslim.integrations.hermes.LLMSlimContextEngine	ContextEngine 插件 llmslim；通过 context.engine: llmslim 选择
Pydantic AI	llmslim[pydantic-ai]（1.0+）	llmslim.integrations.pydantic_ai.llmslim_history_processor	历史记录处理器，置于 ProcessHistory(...) 中或传入 history_processors=[...]

from pydantic_ai import Agent
from pydantic_ai.capabilities import ProcessHistory
from llmslim.integrations.pydantic_ai import llmslim_history_processor

agent = Agent(
    "openai:gpt-5",
    capabilities=[ProcessHistory(llmslim_history_processor(max_tokens=8_000))],
)

设置说明、可运行示例及其输出： gptme、 Hermes Agent、 Pydantic AI。

---

🛡️ 安全架构：来源隔离

基于祈使关键词（"Must"、"Always"、"Action Required"）对句子进行朴素评分的压缩算法会引入严重漏洞：间接提示词注入放大。攻击者将恶意指令注入检索到的 RAG 文档后，可能诱使压缩器保留攻击载荷，同时丢弃合理的上下文。

我们在 LLMSlim 内部发现了这个问题，并在 v0.3.1 中修复。未发布 CVE 或安全公告，该问题也没有官方 CVSS 评分。

LLMSlim 通过明确的上下文角色信任边界解决此问题：

 ┌────────────────────────────────────────────────────────┐
 │           HIGHEST TRUST (Priority Tier 4)              │
 │  System & Developer Prompts (Strictly Protected)       │
 ├────────────────────────────────────────────────────────┤
 │           INTERMEDIATE TRUST (Priority Tier 2-3)       │
 │  Direct User Input                                     │
 ├────────────────────────────────────────────────────────┤
 │           PROVENANCE-LOCKED (Priority Tier 0-1)        │
 │  RAG Documents • Assistant History • Tool Outputs     │
 │  *Cannot reach Tier 4 through imperative patterns*     │
 └────────────────────────────────────────────────────────┘

1. 强化优先级锁定：标记为 ContextRole.RAG、ContextRole.TOOL 或 ContextRole.ASSISTANT 的内容，无论使用何种祈使句语法，都无法获得 Tier-4 优先级。
2. 受随机数保护的重写分隔符：当输入包含类似围栏的令牌（例如 ---END TEXT---）时，重写模板中的围栏会使用每次调用随机生成的随机数，因此嵌入其中的令牌无法关闭文本区域。输入本身不会被修改。
3. 默认不可信，而非过滤：这些保护措施会阻止注入文本获得优先级，但不会删除它。plan_context 和 ContextRuntime 会在最终上下文中将其标记为 trusted="false"，以便你的模型和应用程序据此处理。

---

🧩 合约安全的工具架构与 MCP 导入

大型 Agent 目录（包含数十或数百个工具定义）会在 Agent 开始思考之前就浪费数千个 token。LLMSlim 推出了合约安全的工具基础设施（v0.4.0 和 v0.5.0）：

from llmslim.tools import (
    canonical_json,
    contract_equivalent,
    fingerprint_tool_schema,
    from_mcp_tool,
    optimize_tool_schema,
)

# 1. Ingest authoritative raw tool definition
raw_tool = {
    "name": "enterprise.search_ledger",
    "description": "Searches financial transaction records by date range.",
    "inputSchema": {
        "type": "object",
        "properties": {"account_id": {"type": "string"}, "limit": {"type": "integer"}},
        "required": ["account_id"],
    },
}

# 2. Parse and safely optimize schema formatting
tool = from_mcp_tool(raw_tool, namespace="finance")
result = optimize_tool_schema(tool)

# 3. Mathematically verify exact contract equivalence
assert result.equivalence.status.value == "EXACT"
assert fingerprint_tool_schema(tool) == fingerprint_tool_schema(result.optimized)

print("Canonical Fingerprint:", fingerprint_tool_schema(result.optimized))
print(canonical_json(result.optimized.raw))

异步 MCP 目录来源（v0.5.0）

需要执行 pip install "llmslim[mcp]"（Python 3.10+），并运行一个 MCP 服务：

import asyncio

from llmslim.mcp import MCPToolCatalogSource, PlanMode, plan_catalog_context


async def main() -> None:
    # Streamable HTTP MCP source with bounded pagination and stale-cache detection
    source = MCPToolCatalogSource.from_streamable_http(
        "http://127.0.0.1:8000/mcp",
        headers={"Authorization": "Bearer local-token"},
    )

    snapshot = await source.list_tools()
    plan = plan_catalog_context(snapshot, mode=PlanMode.FULL)

    print(f"Catalog contains {len(snapshot.tools)} tools ({plan.metrics.catalog_tokens} tokens)")


asyncio.run(main())

---

📊 基准测试与彻底透明

许多库声称提示词压缩率高达 90%，却没有提供依据。在 LLMSlim，我们践行彻底的基准测试透明度：

第 3 轮：Core 0.9.0 与记忆系统及压缩器对比，成本优先

测试于 2026 年 10 月 13 日至 15 日进行，使用留出的测试问题。每个系统都由 Claude Haiku 5.5 使用相同的回答提示词和评审标准进行测试。Mem0 和 Zep 使用各自的基准测试框架；LLMLingua-2 和 LongLLMLingua（LLaMA-2-7B，float16）则使用其已发布的设置。每个压缩器的上下文均在公开的 Kaggle 笔记本中构建，并固定到某个提交版本。每个单元格都列出准确率，以及完整处理 1,000 个问题的成本，按标价计算：回答调用、Mem0 和 Zep 的记忆构建调用，以及各系统的计算成本。完整表格、置信区间、薄弱环节和每个回答见：benchmarks/live/round3。

基准测试	LLMSlim 0.9 + 重排器	LLMSlim 0.9（无模型）	Mem0	Zep	LongLLMLingua	LLMLingua-2	检索基线*	完整上下文
LoCoMo，1,307 个问题，约 2,500 个 token	93.0% · $0.95	91.7% · $0.89	91.0% · $2.66	74.4% · $6.24	73.3% · $7.01（300 个问题）	34.1% · $0.43	85.2% · $0.90	95.1% · $0.83（缓存）
LongMemEval-S，180 个问题，约 10,000 个 token	74.4% · $2.21	77.8% · $2.13			未运行	15.6% · $8.43	80.6% · $4.45	77.8% · $90.21
LongMemEval-S，Mem0 的 60 个问题，约 2,500 个 token	78.3% · $1.04	71.7% · $0.96	76.7% · $220.88				80.0% · $3.36	78.3% · $90.20
LongMemEval-S，Zep 的 24 个问题，约 2,500 个 token	87.5% · $1.01	87.5% · $0.94	87.5% · $219.48	58.3% · $697.56			83.3% · $3.28	91.7% · $90.22
NaturalQuestions，2,255 个问题，使用 25% 的 token	73.5% · $0.33	60.6% · $0.30			70.5% · $1.32（1,000 个问题）	52.5% · $0.87	73.9% · $0.30	78.4% · $0.65
HotpotQA，2,000 个问题，使用 40% 的 token（精确匹配）	52.2% · $0.15	52.4% · $0.13			50.4% · $0.77（1,000 个问题）	46.7% · $0.47	50.5% · $0.13	58.0% · $0.24

* 在 LoCoMo 和 LongMemEval 上使用基于轮次的稠密检索（Qwen3-Embedding-0.6B）；在 NaturalQuestions 和 HotpotQA 上使用普通重排器。Mem0 使用其排名前 50 的记忆，但在 Mem0 自身样本上使用排名前 200 的记忆。LongLLMLingua 使用预先注册的样本；在相同的问题上，使用重排器的 LLMSlim 在 LoCoMo 上得分为 93.3%（+20.0，95% CI +15.0 至 +25.0），在 NaturalQuestions 上为 72.7%；默认 LLMSlim 在 HotpotQA 上为 53.3%。缓存未命中时，每 1,000 个 LoCoMo 问题的缓存完整历史成本为 $4.48。

LLMSlim 的不足之处：

• NaturalQuestions 上不使用重排器时。 默认词法模式得分为 60.6%，普通重排器为 73.9%：改写的问题需要语义匹配，因此开放域检索应使用重排器。
• LongMemEval 上的稠密检索。 在 10,000 个 token 时，稠密检索得分为 80.6%，LLMSlim 为 77.8%；在 2,500 个 token 时分别为 76.1% 和 74.4%，成本约为其两倍。180 个问题上的差距均不显著，但方向一致。一个在开发问题上缩小差距的修复未能在测试集上奏效，因此没有纳入 0.9.0。
• 1,000 个 token 下的多跳和时间类问题。 在 LoCoMo 的多跳问题上，Mem0 排名前 20 的记忆优于默认 LLMSlim（88.7% 对 80.3%）；在时间类问题上也同样如此（93.4% 对 85.7%）。使用重排器后，LLMSlim 的总体表现领先（90.5% 对 88.7%）。
• 缓存的完整历史。 当对话中的问题连续提出时，缓存的历史在 LoCoMo 上达到 95.1%，成本为 $0.83，优于所有压缩上下文。

长文档与 Agent：第 2 轮，Core 0.8.0

所有配置使用相同的模型和提示词；截断时使用的 token 数量与 LLMSlim 完全相同，并且代码冻结后，每个套件都在新样本上重新运行了一次（benchmarks/live）。0.9.0 仅改变了纯文本聊天记录的选择方式。

基准测试	完整上下文	LLMSlim 0.8 + 重排器	LLMSlim 0.8（无模型）	截断，预算相同	Token 数（完整 → LLMSlim）
LongBench v1，210 个样本（宏平均）	54.9	54.2	54.9	45.2	15,532 → 5,232
… 新的 210 个样本	55.1	55.4	55.0	46.8
LongBench v2，180 个问题（准确率）	60.0	55.6	53.9	48.3	30,493 → 8,469
SWE-bench Verified Mini，50 个问题（已解决）	36-38	未运行	38	未运行	每个任务 48-58k → 51k

重排器是可选的（relevance="semantic"，来自 semantic extra 的 22M 参数交叉编码器）；不使用它时，LLMSlim 完全不运行任何模型。

说明

Schema 税测量：在我们 v0.4.0 的基准测试中，对为本仓库编写的 18 个目录中的 375 个合成工具 Schema 进行测试（见数据集卡片），当基线已经是紧凑的规范 JSON 时，无损 Schema 压缩节省了 0 个 token（0.00%）。我们如实公开这一结果：没有节省时，我们绝不会声称存在虚构的收益。

v0.6 自适应规划器（冻结的离线套件）

方法	预算达成率	上下文缩减率	必需事实	硬性约束	平均延迟*
原始完整上下文	71.4%	0.0%	100%	100%	仅测量
朴素前缀	100%	9.2%	100%	100%	2.21 ms
固定比例压缩器	78.6%	9.6%	94.0%	96.4%	26.55 ms
自适应规划器	96.4%	11.4%	100%	100%	208.02 ms

这个包含 28 个案例的数据集涵盖聊天、RAG、工具、混合、外部来源和 12 种语言的多语言案例。唯一导致自适应规划不可行的是一个有意设计为不可能完成的完整目录案例；报告中对此进行了明确说明。这些基于任务的检查并非由 LLM 评判，也不代表普遍的质量结论。延迟仅适用于已检入的运行和硬件。请参阅发布门槛结果、原始结果和冻结的数据集。 未在没有明确选择加入且未提供凭据的情况下运行实时 Sarvam 测试框架。

---

🖥️ 命令行界面（CLI）

直接从终端压缩文件、流或提示词：

# Compress a document to 50% ratio
llmslim document.txt -o compressed.txt --ratio 0.5

# Pipeline integration with jq / curl
cat input.txt | llmslim --ratio 0.4 --mode rag > rag_context.txt

# Inspect token count differences
llmslim document.txt --stats

---

📋 更新日志

每个版本（包括 0.11.2）的发行说明都位于 CHANGELOG.md 和 GitHub Releases。

---

🤝 生态集成

LLMSlim 是一个不预设立场的上下文预处理器。这些集成已随核心版本提供；它们都不会代你发送请求。每个会消耗供应商额度的集成，都会在请求离开进程前通过 UsageGuard 检查（每分钟速率、生命周期请求上限，以及以 INR、USD 或查询次数计量的额度上限；可通过 LLMSLIM_<VENDOR>_* 变量配置；请参阅 .env.example）：

其他框架没有专用适配器。LLMSlim 适用于任何能传递普通消息列表（{"role": ..., "content": ...} 字典）或文档字符串的框架；你只需编写少量胶水代码，将 LLMSlim 的输出传递给客户端。

---

📜 许可证与引用

LLMSlim 是基于 MIT License 许可的开源软件。完整详情请参阅 LICENSE。

如果你在研究或生产系统中使用 LLMSlim，请引用：

@software{llmslim2026,
  author = {Yashvardhan Thanvi},
  title = {LLMSlim: Deterministic Context Compression and Contract-Safe Tool Schemas for LLMs},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/Thanatos9404/llmslim}
}

---

Agent Context Runtime（v0.7.0）

版本 0.7.0 为 Agent 应用添加了逐轮上下文路径（0.7.0 未发布到 PyPI；请安装 0.7.1 或更高版本）。 宿主提供消息、检索到的文档、记忆、工具结果和已授权的工具架构；LLMSlim 返回经过质量检查的模型输入和可解释的本地跟踪记录。模型调用和工具执行仍由宿主负责。

from llmslim import ContextRuntime, generic_request

runtime = ContextRuntime(model="sarvam-105b", max_input_tokens=8_000)
prepared = runtime.prepare_sync(
    user_input="When does Acme renew?",
    messages=[{"role": "system", "content": "Use verified dates."}],
    documents=[{"id": "contract", "content": "Acme renews on 9 November 2026."}],
)
if prepared.feasible:
    request = generic_request(prepared)  # the host sends this to its model
    print(request["messages"])
    print(prepared.trace.explain())

此运行时包含 ContextEnvelope、ContextGraph、ContextPolicy、渐进式规划、质量门控、有界内存会话，以及适用于通用、Sarvam、OpenAI 兼容和纯文本 OpenAI Agents 应用的无执行适配器。默认情况下，ContextTrace 不包含提示词正文。 现有的 compress() 和 plan_context() API 仍可继续使用。

参阅架构、 安全模型、 集成、 迁移指南、 基准测试和 工程报告。

缓存感知上下文运行时（v0.7.1）

缓存规划是一个可选层，用于重复的 Agent 轮次。LLMSlim 可识别提供商可见的稳定前缀，在安全的情况下保留只追加的对话上下文，为缓存敏感设置生成指纹，并将本地缓存估算与提供商报告的用量分开显示。按租户隔离的 CacheManager 会存储元数据和提供商引用，不存储提示词正文或 KV 张量。

from llmslim import CacheManager, CachePolicy, ContextRuntime

runtime = ContextRuntime(
    model="generic-128k",
    cache_policy=CachePolicy(mode="auto", provider="openai", tenant_id="my-workspace"),
    cache_manager=CacheManager(),
)
prepared = runtime.prepare_sync(
    session_id="conversation-1",
    messages=[{"role": "system", "content": "Use verified sources."}],
    user_input="What changed?",
)
print(prepared.trace.to_dict()["cache"])

无执行请求构建器支持 OpenAI Responses、Anthropic Messages、Gemini 缓存资源和可自托管的 vLLM。高级进程内 Transformers 适配器可验证 KV 延续状态。OpenAI 有状态提供商续接和 Gemini 缓存资源创建需要宿主明确选择启用。Sarvam 提示词缓存尚未经过验证，默认禁用。Context Inspector 可显示前缀分段和缓存诊断信息，而不调用提供商。参阅缓存指南、 多轮基准测试和 工程报告。

开源安全工具

Snyk 为开源项目提供开发者安全工具。了解更多信息，请参阅其安全开发者计划。