Metadata-Version: 2.4
Name: silo-memory
Version: 0.3.2
Summary: Local long-term memory for coding agents (SQLite FTS5 + keyword graph + skills for Claude Code / Codex / OpenCode / Cursor / Grok)
Project-URL: Homepage, https://github.com/flynn-eye/silo-memory
Project-URL: Repository, https://github.com/flynn-eye/silo-memory
Project-URL: Issues, https://github.com/flynn-eye/silo-mem/issues
Author-email: flynn-eye <939649107@qq.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,cli,codex,coding-agent,cursor,fts5,memory,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.140.0
Requires-Dist: filelock>=3.20.0
Requires-Dist: jieba>=0.42.1
Requires-Dist: sqlite-vec==0.1.9
Requires-Dist: typer>=0.27.0
Requires-Dist: uvicorn>=0.51.0
Description-Content-Type: text/markdown

# Silo

[![PyPI version](https://img.shields.io/pypi/v/silo-memory)](https://pypi.org/project/silo-memory/)
[![Python](https://img.shields.io/pypi/pyversions/silo-memory)](https://pypi.org/project/silo-memory/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[English](README_EN.md) | 中文

**Coding agent 的本地长期记忆系统。**

Claude Code、Codex、Cursor 等 agent 每个会话都"失忆"——用户的偏好、项目事实、历史经验无法沉淀。Silo 让任意 agent 在每次对话开始时**召回**相关记忆，在任务交付后**沉淀**新经验。

- **纯本地**：Markdown 原文 + SQLite FTS5 索引 + 关键词关系图，全部存储在本机，不发送数据到外部服务
- **即插即用**：为 Claude Code / Codex / OpenCode / Cursor / Grok 提供 `search` 与 `update` 两个技能，一条命令安装
- **零端口**：CLI 优先，无需常驻服务；可选 Web 管理台

## 安装

```bash
uv tool install silo-memory        # 推荐
pipx install silo-memory           # 或
pip install silo-memory            # 或
```

安装技能到 agent：

```bash
silo install                # 自动检测已安装的 agent
silo install claude-code    # 或指定 agent
```

开发安装：

```bash
git clone https://github.com/flynn-eye/silo-mem.git && cd silo-mem
uv tool install -e .
```

## 快速上手

```bash
# 写入一条记忆
silo add "项目使用 pnpm 管理前端依赖" --tags "my-project 前端 pnpm 约定"

# 搜索
silo search "前端依赖管理" --tags "my-project 前端" --limit 5

# 启动 Web 管理台
silo server                 # http://127.0.0.1:8900
```

## CLI 参考

```bash
silo search "关键词" --tags "标签 标签" --limit 5   # 搜索（JSON，按相关度排序）
silo add "记忆内容" --tags "标签 标签"              # 新增
silo replace <old_id> -c "新内容" -t "标签"         # 删旧增新
silo delete <id>                                   # 删除
silo reindex                                       # 从 Markdown 源重建索引
silo graph link "A" "B" -r SAME_AS                 # 建立标签关系
silo graph unlink "A" "B" -r SAME_AS               # 删除标签关系
silo graph expand "A" --depth 2                    # 查看标签扩展范围
silo graph status                                  # 图规模及状态
silo server                                        # Web 管理台
silo install [auto|all|claude-code|codex|opencode|cursor|grok]
silo uninstall [all|<agent>]
silo upgrade                                       # 自更新
```

## 搜索与关键词图

搜索同时覆盖记忆内容和 tags。`--tags` 中的标签先通过本地关键词图做最多两跳的有限扩展，再以衰减权重加入 FTS5 检索；精确关键词和原始标签始终比图扩展标签权重更高。查询经 jieba 预分词后作为字面 token 匹配，`foo-bar`、`C++` 等文本不会被解释成 FTS5 查询语法。

关键词图支持 `SAME_AS`、`ALIAS_OF`、`PARENT_OF`、`CHILD_OF` 和 `RELATED_TO` 显式关系。同一条记忆中的 tags 会自动形成低权重 `CO_OCCURS` 边。递归查询有跳数、最低得分、去环和结果数量限制，避免关系无限扩散。

## 技能如何工作

- **silo-search**：用户每次提交新提示词时，agent 提炼 keywords + tags 调 `silo search`；query tags 自动经过关系图扩展，命中的历史记忆作为上下文注入。Claude Code 额外注册 UserPromptSubmit hook 实现自动召回（`--no-hook` 可关闭）。
- **silo-update**：任务交付后或用户要求"记住"时，agent 自评经验价值 → 查重 → 命中旧记忆则合并后 `silo replace`，无命中则 `silo add`。只有用户明确确认时才调用 `silo graph link`。

## Web 管理台

提供"记忆档案"和"关键词图"两个视图。关键词图使用 Canvas 力导向布局展示有界子图，支持按标签定位、关系类型筛选、节点详情查看。

默认只监听回环地址。如需局域网访问：`silo server --host 0.0.0.0 --allow-remote`（无鉴权）。

## 存储结构

```
~/.silo/
├── memories/*.md    # 原文（frontmatter: id/tags/created_at），人可读、可备份
├── index/search.db  # SQLite FTS5 索引（可从 Markdown 重建）
├── graph.db         # 标签节点、关系边、证据
├── ops.db           # 操作日志
└── .silo.lock       # 跨进程读写锁
```

索引损坏或 schema 变化时自动重建。所有写操作在跨进程锁内完成，支持多 agent 并发。

## 开发

```bash
uv sync                       # 后端依赖
cd web && pnpm install        # 前端依赖（Vite + React + pnpm）
pnpm dev                      # 前端热更新（API 代理到 :8900）
uv run silo server            # 后端
uv run pytest                 # 测试
uv build                      # 构建（自动触发前端编译）
```

## 技术栈

SQLite FTS5 · sqlite-vec · jieba · typer · FastAPI · uvicorn · React · Vite · react-force-graph-2d

## License

[MIT](LICENSE)
