A Ingram

Aingram（精简版）

找到正确上下文的代理内存。每一次。当地。

pip install aingram

   

______________________________________________________________________

大多数人工智能存储系统都是带有搜索栏的文件柜。存储所有内容，稍后搜索，希望正确的东西回来。

Aingram是不同的。它在运行 同时发出三个检索信号 --全文搜索、语义向量搜索和知识图遍历，并使用往复式排名融合将它们融合到一个排名结果中。万物皆有生命 一个SQLite文件 在你的机器上。没有云。没有API密钥。没有供应商可以信任你的代理商的记忆。

在LongMemEval（人工智能内存最严格的公共基准）上，Aingram的检索管道在前3个结果中找到了正确的上下文 对于每一个查询 当证据存在时。在具有完整嘈杂对话历史的真实基准上，它在前10名中列出了正确的会话 95.5%的查询.端到端答案准确性（检索→ gpt-4o-mini）达到 72.8% 在所有问题类型中。

from aingram import MemoryStore

with MemoryStore('./agent_memory.db') as mem:
    mem.remember('The API rate limit is 100 req/min. Exceeding it causes silent drops.')
    mem.remember('Deployment takes ~3 min. Always run migrations before the container swap.')

    results = mem.recall('what do I need to know before deploying?', limit=5)
    for r in results:
        print(r.score, r.entry.content)

______________________________________________________________________

数字

基准 LongMemEval （Wu等人，ICLR 2025）——在多会话对话历史中，500个手工策划的问题，平均11.5万个标记。所有运行在RTX 4060 8GB上。无重新评级模式。检索循环中没有LLM。

这些数字意味着什么：

• recall_any@3=1.000（预言机）： 当证据存在时，Aingram会将500个实例中每个查询的正确会话放在前3个结果中。您的代理始终可以使用正确的上下文。
• recall_any@10=0.955（实际值）： 在真实的嘈杂对话历史中——每个查询大约有40个嘈杂会话——95.5%的查询中，正确的会话出现在前10名中。这为任何下游LLM精度设定了上限。
• 22ms中值检索延迟 --纯本地管道，无网络往返。

端到端答案准确性（LongMemEval-S）

完整的管道精度：AIngram检索→ gpt-4o-mini在多会话对话历史中回答500个问题。所有类别都使用gpt-4o-mini与已发布的基线进行干净的可比性。

⚠️ 时间推理说明： 60.2%的数字始终使用gpt-4o-mini，这与已公布的基线相比是干净的。用gpt-4o运行该类别会产生收益 98/133 (73.7%)，提高了13.5pp，并将整体准确率提高到76.4%（382/500）。该分数与已公布的gpt-4o-mini基线没有直接可比性。

检索速度随语料库大小而变化。矢量搜索是大规模的主要成本——Aingram的QJL两遍压缩使其易于管理：

QJL的两遍方法（压缩候选人→ float32重新排名）在大约30K的条目下与暴力破解持平，并在阈值以上提供有意义的加速。

______________________________________________________________________

为什么不直接使用矢量数据库呢？

单信号检索失败。语义相似性很强大，但会中断：

• 精确术语 --关于“100个请求/分钟的速率限制”的查询可能在语义上与没有FTS的“硬上限：100个/分钟”的内存不匹配
• 实体关系 --“Alice对auth做出了什么决定？”需要图遍历，而不是余弦相似性
• 关键字优先查询 --代理经常使用特定的技术术语进行搜索，其中BM25的性能优于密集检索

Aingram运行所有三个信号并将其融合。混合始终优于任何单一信号，特别是在代理实际进行的精确、特定于领域的查询方面。

______________________________________________________________________

运作原理

Agent query
    │
    ├──▶ FTS5 (keyword)                        ─┐
    ├──▶ sqlite-vec + QJL two-pass (semantic)  ─┤──▶ RRF fusion ──▶ ranked results
    └──▶ Knowledge graph (entity)              ─┘

FTS5全文搜索 --SQLite的原生全文索引。快速，无需嵌入，非常适合精确的术语和技术字符串。

sqlite-vec矢量搜索 --使用密集语义检索 nomic-embed-ext-v1.5 通过ONNX在本地运行。768维嵌入式、CPU或GPU。没有外部API。

QJL双通道矢量搜索 --在较大的语料库规模下，向量搜索在检索延迟中占主导地位。Aingram使用量化Johnson-Lindenstrauss（QJL）两遍方法：对压缩的量化向量进行快速的第一遍，缩小候选池，然后对完整的float32向量进行精确的第二遍，重新排序幸存者。这以一小部分召回率换取了大规模的显著较低延迟——盈亏平衡点约为30K个条目，高于此点，QJL比暴力float32搜索更快，没有明显的质量损失。

知识图遍历 --从内存条目中提取的实体和关系。通过CTE解决多跳查询。“Alice对auth做出了什么决定？”查找实体，遍历关系，返回相关条目——即使查询与条目不完全匹配。

互惠排名融合 --将所有三个信号的结果合并并重新排序。每个信号的排名位置，而不是原始分数，有助于最终的顺序。这使得融合对信号之间的差异具有鲁棒性。

______________________________________________________________________

一个文件中的所有内容

你的整个代理内存——条目、嵌入、实体图、签名链——都存在于一个SQLite文件中。无需管理单独的矢量数据库。没有图形数据库。没有外部嵌入服务。没有Docker容器。

agent_memory.db     ← that's it

复制它。用备份 cp.用任何SQLite客户端检查它。在代理商之间共享。将其导出为JSON格式。把它进口到别的地方。

这是一个深思熟虑的设计选择。需要基础设施才能运行的内存很脆弱。作为文件的记忆是持久的。

______________________________________________________________________

加密完整性

每个内存条目都经过Ed25519签名，并链接到防篡改哈希链中。您可以验证内存自写入以来是否未被修改，这在代理之间共享内存或跨信任边界存储内存时非常有用。

result = mem.verify()
# VerificationResult(valid=True, session_id='...', entries_checked=1247, errors=[])

______________________________________________________________________

实体抽取与知识图谱

# After 'User Alice approved the migration to Clerk on Jan 15.'
# is stored, the graph contains:
#   Alice ─[approved]─▶ migration (valid_from: 2026-01-15)
#   migration ─[uses]─▶ Clerk

results = mem.recall('what did Alice decide?')
# Returns entries linked to Alice via graph traversal,
# not just entries that mention "Alice" by text

直接查询图形：

aingram --db ./agent_memory.db graph "Alice"
aingram --db ./agent_memory.db entities

______________________________________________________________________

记忆巩固

跑 aingram consolidate （或 mem.consolidate())随着时间的推移，清理累积的内存。整合分为四个步骤：

1. 衰变 --降低最近未访问过的内存的重要性得分（始终处于活动状态，无需配置）
2. 矛盾检测 --找到关于同一实体的成对记忆，这些记忆说的是相互冲突的事情，并将较旧的记忆标记为已被取代
3. 合并 --在重复记忆附近聚集并合成单个规范条目（需要Ollama）
4. 知识综合 --将相关观察结果链总结为更高层次的结论（要求Ollama）

矛盾检测 由通过ONNX运行时运行的本地DeBERTa-v3 NLI模型提供支持，在推理时不需要LLM或网络调用。在中启用它 ~/.aingram/config.toml:

contradiction_backend = "deberta"   # or "llm" to use Ollama instead
contradiction_threshold = 0.7       # confidence cutoff (0.0–1.0)

DeBERTa型号（约740MB）在首次使用时从HuggingFace下载并在本地缓存。为了使矛盾检测工作，实体提取必须在您的记忆上运行(aingram[extraction] 必填），因此条目可以按它们提到的实体进行分组。

aingram consolidate        # run all steps, print JSON summary

捕获守护进程自动整合： 如果捕获守护进程正在运行，它可以在每N个摄入的内存中自动触发整合。集 consolidation_interval_records 在 [capture] 配置的一部分（默认值：50，设置为0以禁用）。

______________________________________________________________________

MCP服务器

安装 aingram[mcp] 并将任何MCP兼容代理（Claude、Cursor、Windsurf、Cline）连接到您的内存存储。

aingram --db ./agent_memory.db mcp

暴露的工具： remember, recall, reference, verify, get_experiment_context以及更多。包含可选的承载令牌身份验证中间件。

添加到MCP配置中：

{
  "mcpServers": {
    "aingram": {
      "command": "aingram",
      "args": ["--db", "/path/to/agent_memory.db", "mcp"]
    }
  }
}

______________________________________________________________________

快速开始

pip install aingram

Python API：

from aingram import MemoryStore

with MemoryStore('./agent_memory.db') as mem:
    # Store a memory
    mem.remember('Deploy always requires a migration run first.')

    # Recall with hybrid search
    results = mem.recall('deployment checklist', limit=5)
    for r in results:
        print(f'{r.score:.3f}  {r.entry.content}')

CLI：

aingram --db ./agent_memory.db status
aingram --db ./agent_memory.db add "API rate limit is 100 req/min"
aingram --db ./agent_memory.db search "rate limiting"
aingram --db ./agent_memory.db entities
aingram --db ./agent_memory.db graph "Alice"
aingram --db ./agent_memory.db export ./backup.json
aingram --db ./agent_memory.db import ./backup.json

GPU嵌入（可选）：

pip uninstall -y onnxruntime
pip install onnxruntime-gpu
pip install "aingram[gpu]"
export AINGRAM_ONNX_PROVIDER=cuda

______________________________________________________________________

多代理模式

AIngram支持并发多代理设置，其中多个逻辑代理共享一个SQLite内存文件。两种形状开箱即用：

• 流程内（最简单）： 多个异步任务共享一个 *单个* MemoryStore 例子发动机内部 threading.Lock 序列化写入。
• 跨流程（或当您希望每个代理归因时）： 每个代理都构建自己的 MemoryStore(db_path, agent_name='agent-N') 指向同一个 .db 文件。SQLite的WAL模式处理多写入器安全。

看 examples/05_multi_agent_shared_memory.py 对于进程内形状的自包含的~100行演示：三个异步代理共享一个 MemoryStore 解决玩具超参数搜索任务，每个代理的 recall() 将兄弟姐妹的发现浮出水面，进行背负式探索。

用于生产级多代理研究集成，包括三种并发模式（模拟/单独/集群）、具有CUDA固定的子流程编排、工作空间隔离和完整的Karpathy autoresearch 连接到AIngram内存层的循环——请参阅配套的repo bozbuilds/aingram AR.

______________________________________________________________________

安装

pip install aingram                   # core — CPU embeddings
pip install "aingram[extraction]"     # + GLiNER entity extraction
pip install "aingram[mcp]"            # + MCP server
pip install "aingram[llm]"            # + Ollama/local LLM client
pip install "aingram[api]"            # + Anthropic API extractor
pip install "aingram[gpu]"            # + CUDA ONNX Runtime wheels
pip install "aingram[capture]"        # + capture daemon (starlette, uvicorn, watchdog)
pip install "aingram[all]"            # everything (except capture and gpu)

______________________________________________________________________

捕获守护进程

安装 aingram[capture] 以实现从AI编码工具自动捕获提示/响应。守护程序在本地运行 localhost:7749 支持Claude Code、Cursor、Gemini CLI、Aider、Copilot、Cline和ChatGPT（手动导出）。

aingram capture start                 # foreground mode
aingram capture start --daemon        # background mode
aingram capture stop                  # stop the daemon
aingram capture status                # show tool status and queue depth
aingram capture install claude_code   # print hook setup instructions
aingram capture on                    # enable all tools
aingram capture off cursor            # disable a specific tool

捕获的交互流通过过滤器管道(@nocapture 选择退出、秘密编辑）到单独的SQLite队列中，然后通过以下方式排入主内存数据库 MemoryStore.remember().通过配置 [capture] 在 ~/.aingram/config.toml 或 AINGRAM_CAPTURE_ENABLED / AINGRAM_CAPTURE_PORT env变量。默认情况下禁用。

______________________________________________________________________

克劳德代码挂钩

AIngram可以直接将相关内存注入Claude Code的上下文窗口——在您键入的每个提示之前和每次文件编辑之前。这让Claude Code可以看到你在各个会话中学到了什么，而无需你问。

aingram hook install        # patches ~/.claude/settings.json
aingram hook uninstall      # removes the hook entries

在引擎盖下， hook install 寄存器 aingram_cc_hook.py 作为非阻塞 UserPromptSubmit 和 PreToolUse 钩子。在每次触发时，AIngram都会向召回守护进程查询相关内存，并将其作为 `` Claude代码使用的XML块。除非找到相关内存，否则不会消耗令牌预算。

召回守护进程 --钩子与本地HTTP服务器通信(localhost:7750)这使ONNX嵌入模型保持温暖，因此钩子响应保持在2秒超时以下：

aingram recall-daemon start    # foreground (the hook auto-spawns this if needed)
aingram recall-daemon stop
aingram recall-daemon status

守护进程在30分钟不活动后自行关闭。

挂钩配置 (~/.aingram/hook.toml):

[scoring]
project_boost = 0.003        # extra weight for memories from the current directory
seen_demote = 0.004          # penalty for memories already surfaced this session
prompt_limit = 8             # max memories injected on UserPromptSubmit
edit_limit = 3               # max memories injected on PreToolUse (Edit/Write)

[session]
seen_cap = 200               # max seen-set size per session
stale_days = 7               # days before seen-set files are pruned

通过env变量覆盖任何值： AINGRAM_HOOK_DISABLED, AINGRAM_HOOK_PROMPT_LIMIT, AINGRAM_HOOK_EDIT_LIMIT, AINGRAM_HOOK_PROJECT_BOOST, AINGRAM_HOOK_TIMEOUT_MS.

______________________________________________________________________

配置

优先级：构造函数kwargs→ 环境变量→ ~/.aingram/config.toml → 默认值。

~/.aingram/config.toml 示例（注意：平面键，核心设置没有节标题）：

embedding_dim = 768
worker_enabled = true
llm_url = "http://localhost:11434"
llm_model = "mistral"
extractor_mode = "local"
contradiction_backend = "deberta"
contradiction_threshold = 0.7
telemetry_enabled = false

[capture]
consolidation_interval_records = 50

______________________________________________________________________

隐私和遥测

任何内存内容都不会离开您的机器。 SQLite数据库、嵌入和实体图保持本地。

默认情况下，CLI可能会发送匿名使用事件：随机安装ID、顶级命令名（例如。 search, add)，以及软件包版本。没有内存文本、查询内容、文件路径或个人数据。

选择退出：

• --no-telemetry 根据任何命令
• telemetry_enabled = false 在 ~/.aingram/config.toml
• AINGRAM_TELEMETRY_ENABLED=false 环境变量

______________________________________________________________________

比较

______________________________________________________________________

出口/进口

# Export everything — entries, graph, vectors
mem.export_json('./backup.json')

# Import into a fresh database
with MemoryStore('./new_memory.db') as fresh:
    fresh.import_json('./backup.json')

# Merge into an existing database (skips duplicates)
with MemoryStore('./existing.db') as existing:
    existing.import_json('./backup.json', merge=True)

______________________________________________________________________

基准测试

从该仓库的克隆中复制检索基准：

# Create synthetic benchmark databases
python scripts/seed_bench_db.py

# Run retrieval and embedding timing
python scripts/bench.py

这 scripts/bench.py 输出给出了每个数据库在1K、10K、50K和100K条目的嵌入成本、向量搜索、FTS5和全混合召回的时间细分。

______________________________________________________________________

发展

git clone https://github.com/bozbuilds/AIngram
cd AIngram
pip install -e ".[dev,all]"
pytest
ruff check aingram/ && ruff format --check aingram/

Python 3.11以上。看 贡献.md 作为指导方针。

______________________________________________________________________

接下来是什么

Aingram Lite是开源检索和存储基础。Aingram Pro添加了构建在其之上的系统——GPU驻留神经缓存、具有间隔重复调度的生物内存整合和多代理同步原语等。 加入候补名单，或查看此仓库以获取更新。

______________________________________________________________________

社区

______________________________________________________________________

许可证

阿帕奇-2.0。看 许可证 和 通知.