内容
# SAM/IA [浅层深渊表现/无限深渊压缩]
[](https://github.com/asthenopheredevelopment-commits/samia/actions/workflows/tests.yml)
[](https://www.python.org/)
受生物启发的持久化记忆系统，适用于长期运行的AI代理和个人知识工作。通过分层架构模拟生物巩固过程，存储、检索、衰减和修复记忆，贯穿多个会话。
---
## 状态
单操作员生产环境使用。该系统每天在一台工作站上运行，尚未在多用户或生产规模部署中进行测试。
---
## 它是什么
SAM/IA实现了一个具有以下功能的持久化记忆层，所有功能都存在于当前的代码库中：
- **分层衰减存储** — 五个层级（热 → 存档）；特定于层级的衰减率；冻结节点存档到磁盘，按需解冻。
- **链图情景检索** — 有向链图，具有双时间边缘间隔；组装代币预算约束上下文，按赫布式共激活权重排名。
- **语义原子臂 + 作曲家** — 第二个检索臂，通过向量查找提供提取的`type:semantic`事实；作曲家将两个臂合并为一个标记的上下文（`ASTHENOS_SEMANTIC_ARM_ENABLED`）。
- **巩固时的事实提取** — 当地LLM在巩固时运行在会话卸载上，写入语义原子累加（默认关闭；`ASTHENOS_FACT_EXTRACT_ENABLED`）。
- **矛盾/替代检测** — 嵌入相似性检测（余弦 >= 0.57，可配置；较高的0.92阈值适用于自动替代和涉及机器生成的语义原子的对），默认开启LLM判断门（自动降级为仅候选人，无本地模型）；自动替代可通过`restore_node`恢复到字节精确。测量的TPR 0.80 / FPR 0.10。
- **REM周期离线巩固** — WAKE/REM状态机；维护作业仅在REM期间运行，并立即让步于主动使用；入口是事件驱动的，而不是基于定时器。
- **内容完整性衰减 + 锚点修复** — 正交衰减轴缓慢侵蚀内容；从写入时间快照进行字节精确锚点修复；在P1/P2中没有不可恢复的损失。
- **赫布式联想网络** — SQLite共激活边缘图（`edges.db`），链图检索对其进行评分。
- **一级海马体快速存储** — 记忆存储（数天至数月）+ 环形存储（容量有界，数小时）；kWTA稀疏代码；通过访问频率或显著性进行晋升。
完整的组件内部和模块映射：参见 [ARCHITECTURE.md](ARCHITECTURE.md)。
---
## 运行它
每个操作都可以在进程中作为库调用，并通过`core/mcp_server/`暴露为MCP工具原语。软件包附带一个可运行的stdio MCP服务器（`samia-mcp-server`控制台脚本）；通过`claude mcp add asthenos-memory -- samia-mcp-server`将其注册到MCP客户端（或让`samia init`为您生成连接）。对于自主维护 - 衰减、空闲重放和REM周期巩固 - 运行维护守护进程：`python -m samia.runtime.maintenanced`（或`samia daemon run`）。模块映射、组件内部和systemd单元：参见 [ARCHITECTURE.md](ARCHITECTURE.md)。
---
## 需求
**操作系统软件包** （股票Ubuntu/Debian桌面版不附带venv/pip）：
```sh
sudo apt install -y python3-venv python3-pip curl
```
**Python**：3.10+。软件包依赖项（由pip自动安装）：
- `numpy`
- `mcp` （FastMCP stdio服务器，需要 - 支持`samia-mcp-server`入口点）
- `sentence-transformers`及其`all-MiniLM-L6-v2` （dim=384，CPU；~90MB，从HuggingFace首次使用时下载）。注意：在仅限CPU的盒子上安装CPU torch轮之前，先安装CPU torch轮以避免~1.5GB的未使用CUDA轮：`pip install torch --index-url https://download.pytorch.org/whl/cpu`
- `[llm]`额外：`llama-cpp-python`用于本地LLM臂（矛盾判断、事实提取、合成）。如果没有它，所有非LLM功能都有效；依赖LLM的功能会回退到`MockBackend`并记录警告。
- `sqlite3` （Python标准库）
- 可选：`inotify_simple`或`pyinotify`用于低延迟文件系统监视（如果不存在，则回退到2秒间隔的轮询）
无需云凭证，无需帐户，无需遥测。所有操作均在本地运行。
**网络操作** - 恰好三个，一次性，全都不是自动的：
1. `pip install` - 来自PyPI的软件包依赖项。
2. 首次`vector.build` - MiniLM嵌入器（~90MB，Apache-2.0）来自HuggingFace。
3. 可选模型获取（`model_fetch.fetch_model`或缺少模型的LLM调用）- 模型的许可证在下载前打印。
除了您调用的内容外，没有其他操作会触及网络 - 没有电话回家，没有更新检查。
**每个引擎下载由`ASTHENOS_MODEL_AUTOFETCH`控制**:
- **未设置（默认值）**：从不进行无声下载。在交互式终端，引擎会打印内容/大小/来源并询问`下载？[y/N]`；在没有终端的情况下，它会拒绝并指出两种补救措施。
- **`1`（永久同意）**：下载会在没有提示的情况下进行 - 代理/CI流程在清除自己的许可门后如何操作。
- **`0`（禁用）**：在所有模式下，每个下载都会被拒绝，并附有可复制粘贴的手动下载指令。（`false`，`no`和`off`也被接受，大小写不敏感。）
MiniLM嵌入器仅从本地缓存加载，因此曾经运行过的盒子始终是无声且快速的 - 仅在真正缓存丢失时才会咨询同意。
---
## 安装
引导安装程序。运行它，它会**自动检测您的盒子**（GPU，systemd，是否存在Claude Code），提出计划，并在安装任何内容之前询问。**幂等**：在已经设置好的盒子（或部分设置好）上重新运行是一个快速的无操作，不会重建。
克隆存储库，然后从克隆中运行安装程序：
```sh
git clone <repository-url> samia && cd samia
bash install.sh # 交互式：检测，显示计划，确认，安装
bash install.sh --dry-run # 打印已解析的计划，不更改任何内容
bash install.sh --yes # 非交互式：接受所有检测到的默认值
```
非交互式地通过管道安装程序（`bash install.sh | bash`样式）运行会根据检测到的默认值进行操作 - 没有tty，没有提示。`curl | bash`一行程序只有在存储库（及其原始URL）公开可访问时才有效；在那之前，使用凭证克隆（`gh auth` / SSH密钥）并从克隆中运行`bash install.sh`，如安装程序自己的私有存储库指导所示。
**使用环境变量覆盖任何选择。** 设置的环境变量将被无声尊重，因此脚本/CI运行不会受到影响：
- `SAMIA_WITH_CLAUDE=1` - 还安装Claude Code（需要当前版本的SAM/IA）
- `SAMIA_SERVICE=1` - 安装并启用维护守护进程作为systemd用户服务（`maintenanced`）；`SAMIA_ENABLE_ARMS=1`还开启语义臂+事实提取在该服务中
- `SAMIA_CUDA=1` - 使用CUDA重建llama-cpp-python进行GPU推理（见下文）
- `SAMIA_UPGRADE=1` - 重新安装/升级现有安装
- `SAMIA_VENV=…` / `ASTHENOS_MEMORY_DIR=…` - 重新定位venv / 内存存储
它做了什么 - 并且只有在不存在时才会：apt-install `python3-venv`，`python3-pip`，`python3-dev`， **`build-essential`** （ `[llm]`臂从源代码编译`llama-cpp-python`，因此需要编译器），`curl`，`git`; 创建venv; `pip install`s `samia[llm]`; 创建内存目录。
### GPU加速（可选，实验性）
SAM/IA **从不要求GPU** - 默认构建仅限CPU，在所有地方运行。使用NVIDIA GPU和匹配的CUDA工具包，您可以为GPU卸载重建本地LLM后端（REM时间判断/事实提取/合成运行更快）：
```sh
SAMIA_CUDA=1 bash install.sh # 使用CUDA重建llama-cpp-python
```
这使用**您自己的**CUDA工具包进行构建 - 从您的发行版或NVIDIA安装它以匹配您的驱动程序（SAM/IA **不**捆绑它；没有项目发布多GB的专有工具包）。`install.sh`检查`nvcc`并在它不存在时跳过GPU构建并附上注释。如果您不想编译？llama-cpp-python发布了适用于常见CUDA版本的预构建CUDA轮（不需要工具包）- 但是非常新的GPU（Blackwell）可能需要源代码构建，直到这些轮赶上。
GPU是 **附加的**：CUDA构建在有GPU时使用GPU，并在没有GPU时自动回退到CPU（没有GPU，VRAM耗尽，驱动程序不匹配）。使用`ASTHENOS_N_GPU_LAYERS`调整（`0`强制CPU；正N进行部分卸载以限制VRAM）。在RTX 5070上验证（CUDA 12.8 - Qwen3-4B在~150 tok/s vs ~6 tok/s CPU，~25×）；其他GPU预计也适用，但尚未测试。
---
## 快速入门（手动步骤install.sh自动化）
最快捷的方式是`samia` CLI（使用软件包安装）：`samia init`创建存储并发出MCP连接，`samia daemon run`启动可选的维护守护进程，`samia status`探测安装。对于最简单的端到端脚本（写入 → 索引 → 回忆，使用`memory_write_node` / `memory_search` API），请参见 [`examples/quickstart.py`](examples/quickstart.py)。下面的手动步骤显示了相同的流程在库级别。
```sh
sudo apt install -y python3-venv python3-pip python3-dev build-essential curl git
python3 -m venv ~/samia_venv && source ~/samia_venv/bin/activate
pip install '/path/to/samia[llm,test]' # 或 plain: pip install /path/to/samia
export ASTHENOS_MEMORY_DIR=~/samia_memory # 默认：~/.local/share/samia/memory
export ASTHENOS_MODEL_AUTOFETCH=1 # 永久同意以下模型下载；未设置 = 引擎在tty上询问并在脚本中拒绝（无静默下载）
```
写入一个记忆，索引它，通过两个臂检索它（不需要LLM）：
```python
import os
from pathlib import Path
from samia.core import frontmatter, vector, context_extension, semantic_recall
md = Path(os.environ["ASTHENOS_MEMORY_DIR"]).expanduser()
# 一个情景节点（由链图证据臂提供）
fm = {"name": "first_fact", "description": "my first memory", "type": "reference"}
frontmatter.write_node(md / "nodes" / "first_fact.md", fm, list(fm.keys()),
"SAM/IA stored this on day one.\n")
# 一个语义原子（由FACTS臂提供；运行时，事实提取生成器为您编写这些 - 该路径需要本地LLM）
fa = {"name": "sem_first_atom", "description": "my first semantic atom",
"type": "semantic", "source": "s01", "valid_from": "2026-06-12",
"tier": "warm"}
frontmatter.write_node(md / "nodes" / "sem_first_atom.md", fa, list(fa.keys()),
"The owner of this memory store likes dense little facts.\n")
vector.build(md) # 首次运行下载MiniLM（Apache-2.0，~90MB）- 由上方的ASTHENOS_MODEL_AUTOFETCH控制；如果没有它，非交互式运行会拒绝而不是静默下载
out = context_extension.chainogram_retrieve(md, "first memory", budget_tokens=2000)
os.environ["ASTHENOS_SEMANTIC_ARM_ENABLED"] = "1"
res = semantic_recall.recall(md, "what does the owner like?", budget_tokens=2000)
print(res["context"]) # 已知事实（原子）+ 会话证据（情景）
```
对于LLM臂（矛盾判断，事实提取），请将`ASTHENOS_FACT_EXTRACT_MODEL` / 判断模型env指向您自己的`.gguf`，或者让内置获取器拉取默认模型（打印许可通知）：
```python
from samia.runtime.model_fetch import fetch_model
fetch_model("Qwen3-4B-Instruct-2507-Q4_K_M") # ~2.5GB, Apache-2.0
```
`core/mcp_server/`提供每个工具的后端函数，附带的`sia-mcp-server`控制台脚本是一个可运行的stdio MCP服务器，暴露给代理套件（`claude mcp add asthenos-memory -- samia-mcp-server`）。
---
## 没有什么
- **没有个人语料库。** 没有记忆节点，链，锚点或开发环境的任何历史记录。软件包仅附带代码。带上您自己的记忆目录。
- **没有捆绑模型。** 软件包不附带任何模型权重。LLM臂使用您提供的本地`.gguf`，或者`runtime/model_fetch.py`可以根据请求下载注册模型（Qwen3-4B，Apache-2.0）- 模型许可证在下载前打印，模型缓存在`~/.local/share/asthenos/models/`下。设置`ASTHENOS_MODEL_AUTOFETCH=0`禁用所有下载。
- **没有云凭证。** 可选的云提供商臂不包含API密钥，并且从不提交到存储库（验证：GATE1扫描，零硬编码秘密）。
---
## 已知限制
- 单操作员测试。尚未测试并发多用户写入相同内存目录，可能不安全。
- 冷启动性能（无先前赫布历史，无一级整合）是测量的地板。温暖存储的生产性能更高，但尚未进行独立基准测试。
- 替换检测器在当前相似性阈值（0.57）和嵌入器（MiniLM-L6-v2）下具有测量的FPR 0.10。两个已知错过案例涉及语义上遥远的重述，在嵌入上限处。
- 事实提取质量随提取LLM的规模而变化。默认注册模型是4B；更强大的本地模型改进语义原子臂（尤其是在写入时解决相对日期）以牺牲较慢的整合。
- 暂时的回忆信封术语（`ASTHENOS_TEMPORAL_*`标志）默认关闭；选择性启用并针对您自己的工作负载进行验证。
## 许可证
**PolyForm Noncommercial 1.0.0**（源代码可用）。免费用于个人，研究，教育和任何非商业用途 - 免费实验。**商业用途需要来自作者的付费许可证**（参见NOTICE）。这不是一个OSI“开源”许可证。
## 平台支持
- **Linux** - 在此处开发和测试；一流。
- **macOS** - 预期兼容（纯Python + POSIX构造，macOS提供；llama-cpp-python有Metal轮）。未经测试 - 欢迎报告。
- **Windows** - 尚未原生支持：几个模块使用`fcntl`文件锁定，而Windows缺乏。**WSL2今天有效。**原生支持是一个包含贡献友好TODO（锁定修补程序+临时路径扫描）。
