# Research Agent Memory

> Local-first, auditable, human-governed memory and learning layer for AI agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-l1871276598-dotcom-research-agent-memory`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [l1871276598-dotcom](https://agentstack.voostack.com/s/l1871276598-dotcom)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [l1871276598-dotcom](https://github.com/l1871276598-dotcom)
- **Source:** https://github.com/l1871276598-dotcom/research-agent-memory

## Install

```sh
agentstack add mcp-l1871276598-dotcom-research-agent-memory
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Local Agent Operating System (LAOS)

LAOS is a local-first, auditable, human-governed memory and learning layer for AI agents. It keeps structured memory, project context, task evidence, reflections, and reusable principles in user-controlled files with rebuildable indexes, so GPT, Codex, Claude, local models, and other agents can reuse knowledge without bypassing human review.

**Current release:** [v0.10.0](https://github.com/l1871276598-dotcom/research-agent-memory/releases/tag/v0.10.0) · Python 3.11+ · macOS acceptance target · [MIT](LICENSE)

[Reproducible local demo](#reproducible-local-demo) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

## Why LAOS

- **Local ownership:** authoritative memory stays in user-controlled files, while derived indexes remain rebuildable.
- **Human authority:** agents create candidates, and only an explicit Review Gate decision can accept them.
- **Auditable, deterministic lineage:** memory and learning artifacts retain traceable source evidence and deterministic processing paths.
- **Model independence:** GPT, Codex, Claude, local models, and other agents can use the same governed knowledge layer.
- **Fail-closed isolation:** workspace, project, confidentiality, and restricted-data boundaries reject mismatches or exclude data by default.

## Current capabilities (v0.10.0)

v0.10.0 includes Memory Core, a unified 12-agent JSON CLI, a deterministic learning chain, controlled conversation review, MCP checkpoint tooling, atomic vault promotion, crash-replay convergence, and GitHub Actions. It provides no autonomous approval, passive browser capture, multi-user authorization, or production deployment outside the local trusted-operator boundary.

## Reproducible local demo

Run this from the repository root with Python 3.11 or later. The demo keeps both authoritative data and derived state in fresh temporary directories, contacts no model API, and removes its files when the demo block ends. The create response includes `"requires_review":true`; the candidate becomes searchable after the explicit `memory.review` acceptance. The subsequent `memory.py index` command incrementally synchronizes the derived index; in this sequence it verifies that the accepted record is already current and is not a prerequisite for acceptance or search.

```bash
(
set -euo pipefail

DEMO_DIR="$(mktemp -d)"
DATA_ROOT="$DEMO_DIR/data"
STATE_DIR="$DEMO_DIR/state"
trap 'rm -rf -- "$DEMO_DIR"' EXIT

python3 src/memory.py init --root "$DATA_ROOT"
python3 src/memory.py db-init \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR"

CREATE_RESULT="$(
  python3 src/laos.py \
    --root "$DATA_ROOT" \
    --state-dir "$STATE_DIR" \
    --task-json '{"type":"memory.create","input":{"type":"principle","title":"Evidence before claims","scope":"global","workspace":"personal","confidentiality":"personal","source":"manual:user_confirmed","confidence":"confirmed","content":"Require evidence before making claims."}}'
)"
printf '%s\n' "$CREATE_RESULT"

CANDIDATE_ID="$(
  printf '%s\n' "$CREATE_RESULT" |
    python3 -c 'import json, sys; print(json.load(sys.stdin)["output"]["candidate_id"])'
)"

python3 src/laos.py \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR" \
  --task-json "{\"type\":\"memory.review\",\"workspace\":\"personal\",\"input\":{\"action\":\"accept\",\"candidate_id\":\"$CANDIDATE_ID\"}}"

python3 src/memory.py index \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR"

python3 src/laos.py \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR" \
  --task-json '{"type":"memory.search","input":{"query":"Evidence before claims","workspace":"personal"}}'
)
```

## 中文说明

LAOS 是一个本地优先、可审计、人工审核受控的 Agent 记忆与学习层。它把结构化记忆、项目上下文、任务结果、反思、策略候选、会话审查和可复用原则统一到本地文件与可重建索引中，供 GPT、Codex、Claude、本地模型和其他 Agent 复用。

## 项目标识与术语对照

- **同一项目的三个名字**（指同一系统）：文档与设计里叫 **LAOS**（Local Agent Operating System）；GitHub 仓库标识为 **`research-agent-memory`**；运行时数据/状态目录名为 **`ResearchAgent`**（见下方"目录布局"）。
- **Phase 与 Stage 是两层、两代术语，不是同一序列，编号也不对齐：**
  - **Phase N（设计/特性流层）**——见 `docs/design/`：Phase 4 = 评估基础，**Phase 5 = 学习链**（子项 S5.1–S5.4）；Phase 1/2 为更早的设计单元（无 Phase 3）。
  - **Stage NN（执行/运行时/测试增量层）**——见 `docs/progress/`、`config/stage*`、`tests/test_stageNN`：Stage 05–17 是 v0.8 → v0.9.0 的交付序列。
  - **关键对照**：本仓库的"**Phase 5 学习链**"在 git 分支与运行时产物里记作 **`stage-07` / `stage_07_learning_loop`**（分支 `codex/stage-07-learning-loop`、`PHASE_STATUS.json` 的 `stage_07_*` 键）——两者指同一工作（**Phase 5 ≠ Stage 7**）。Human Review Phase（进行中）延续 Phase 5，设计基线在 `docs/design/phase-5/`。

## 当前版本

- 当前正式版本：`v0.10.0`
- SQLite schema：`v3`
- Python：`3.11+`
- 当前验收平台：macOS
- 后置平台：Linux、Windows
- 运行边界：本地、可信操作者、命令行或受控本地服务

当前实现、集成、验收和发布范围仅承诺 macOS。Linux 与 Windows 兼容性将在 macOS 功能完整性和集成验收完成后作为独立阶段处理，不作为当前交付门禁。

`v0.10.0` 由发布 PR #39 squash merge 到 `main`（合并提交 `77b3c6d`，`v0.10.0` tag 打在该提交上）。发布门禁记录为 **879 项通过 / 0 失败**（v0.9.0 基线为 508，四条特性流累积 508 → 787 → 866 → 879）；四轮外部发布评审收敛至 GO，`release_readiness` 为 `passed`，`deployment` 为 `not_applicable`（本地优先纯源码发布）。发布详情见 [v0.10.0 发布准备记录](docs/progress/2026-07-11-v0.10.0-release-preparation.md)。

**v0.10.0 在 v0.9.0 基线上新增四条特性流**：原子 vault 晋升、Phase 4 评估基础、Handoff 能力（第 12 个 registry agent）、**Phase 5 学习链（S5.1–S5.4）**。

> 上一版 `v0.9.0`：PR #29 squash merge（合并提交 `c21da74d`），Stage 17 本地 508 项测试，详见 `docs/progress/2026-07-06-v0.9.0-release-preparation.md`。

## 已实现能力（截至 v0.10.0）

### Memory Core 与安全边界

- Markdown / JSONL 权威数据源与可重建 SQLite FTS5 索引
- ChatGPT 官方 ZIP 手动导入与手动文件归档
- 结构化记忆、workspace / project / confidentiality / 时间有效性
- candidate-only 创建与统一 Review Gate
- restricted 内容默认不进入搜索、Context Pack 或外部调用上下文
- Trusted Memory Loop、写前校验、事务回滚、重建索引和 durable journal

### 统一 12 Agent JSON CLI

`src/laos.py` 通过一个精确注册表提供：

- Import Agent
- Memory Agent
- Search Agent
- Review Agent
- Context Agent
- Deterministic Reflection Agent
- Policy Agent
- Low-risk Candidate Agent
- Loop Coordinator Agent
- Conversation Review Agent
- Reflection Record Agent
- Handoff Agent（`handoff.write` / `handoff.update`，workspace 绑定的项目 handoff 写入）

Orchestrator 只负责上下文准备、精确路由和结果校验，不承载审核或持久化业务逻辑。

### 确定性学习链

```text
finalize
→ loop.reflect
→ loop.suggest-policies
→ loop.generate-candidate
→ Review Gate
```

已实现：

- 幂等 Loop run v2 合约
- v1 与早期 v2 兼容读取
- 结构化 `root_cause` 与 `next_change` 证据
- 确定性 Reflection artifact
- Policy 精确去重和显式相反指令冲突检测
- 固定三条独立 task/result 指纹阈值
- workspace / project 分区证据聚合
- 两阶段 candidate recovery
- 轻量 `loop.coordinate` 编排

### 会话反思与模型后端

- Conversation Review prepare / apply
- 周期性 `reflection.record`
- 可插拔 ModelBackend registry
- Codex backend
- OpenAI-compatible backend
- Review state、procedure proposal 和 session 状态

### Runtime、Bridge 与 MCP checkpoint

- Agent Runtime、Tool Registry 和 SessionStore
- Procedure 生命周期与 curator 流程
- Bridge Event Inbox、projector 和 crash recovery
- MCP stdio 与回环 Streamable HTTP 服务
- 显式 `laos_capture_checkpoint` 工具及验证流程
- 只读、分区受控的 `memory_search` 工具
- 写入受控的 `handoff` 工具（仅限 source-backed 且 workspace 匹配的活动项目，sha256 冲突检测，原子写入）
- 自动更新 Loop 的真实 baseline → review → verification → comparison 验收入口
- `tools/developer_bridge_adapter.py` 提供固定配置、固定作用域的 checkpoint 捕获、session 搜索和 session 读取入口

Developer Bridge Adapter 不接受任意路径、命令或环境注入；data、state、code 路径必须相互隔离，输入输出有固定大小边界，越权、冲突和不安全路径按 fail-closed 处理。

MCP checkpoint 是显式工具通道，不是浏览器侧被动、无损或自动对话采集。真实 ChatGPT 五轮写入验收仍受当前账户能力限制。

## 硬性安全边界

1. Agent 只能创建 `candidate`，不能直接写入 `active` memory。
2. `active` 只能通过 Review Gate 产生。
3. Reflection、Policy、Candidate、Coordinator 和会话审查流程都不会自动接受候选。
4. `loop.coordinate` 不执行任务、不后台监听、不自动重试。
5. Policy Agent 不自动修改提示词、代码、Agent 行为或 `memory_rules.md`。
6. 三条证据必须来自不同 task/result 指纹，并属于同一 workspace 与 project 分区。
7. MCP、HTTP 和 Bridge 服务只适用于本地可信操作者；当前没有多用户认证和能力授权。
8. 真实记忆、数据库、PDF、日志、缓存、凭据和受限资料不得提交到 GitHub。

## 当前不实现的能力（v0.10.0 范围外）

- 浏览器侧被动、无损 ChatGPT 对话采集
- 自动 policy approval
- 自动 candidate accept 或 active-memory promotion
- 无人值守后台重试或自主任务执行
- 语义冲突自动解决
- 真实向量数据库和 embedding 检索
- 多用户认证与 owner/agent 授权
- GUI、Web 前端或桌面应用
- 大型自主 Coordinator / Meta Planner
- 内置文献管理系统扩展
- 当前阶段的 Linux 与 Windows 发布承诺

文献、Zotero、EndNote、网页和其他外部来源后续只通过 Adapter 或外部接口接入，不进入 Memory Core 主线。

## 数据与状态目录

权威数据目录由用户指定，例如：

```text
ResearchAgent/
├── memory/
├── imports/
├── manuscripts/
├── exports/
└── backups/
```

本地派生状态目录例如：

```text
~/Library/Application Support/ResearchAgent/
├── memory.sqlite
├── sessions.sqlite
├── bridge_events.sqlite
├── review_state.sqlite
└── loop_engineering/
    ├── runs/
    └── generated_candidates/
```

SQLite、WAL/SHM、缓存、日志和 Loop runtime artifacts 不应放入 iCloud 数据目录，也不应提交到 GitHub。

## 快速开始

```bash
REPO_ROOT="/path/to/research-agent-memory"
DATA_ROOT="$HOME/Library/Mobile Documents/com~apple~CloudDocs/ResearchAgent"
STATE_DIR="$HOME/Library/Application Support/ResearchAgent"

cd "$REPO_ROOT"
```

推荐本地初始化：

```bash
python3 tools/setup_local.py \
  --data-root "$DATA_ROOT" \
  --state-dir "$STATE_DIR" \
  --profile personal \
  --workspace personal
```

也可以手动初始化核心数据与索引：

```bash
python3 src/memory.py init --root "$DATA_ROOT"
python3 src/memory.py db-init \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR"
python3 src/memory.py validate --root "$DATA_ROOT"
python3 src/memory.py index --root "$DATA_ROOT" --state-dir "$STATE_DIR"
python3 src/memory.py doctor --root "$DATA_ROOT" --state-dir "$STATE_DIR"
```

## LAOS JSON CLI

CLI 接受 `--task-json` 或 UTF-8 `--task-file`。成功时输出单行规范 JSON；失败时输出安全错误 JSON 并返回非零退出码。

### 创建候选记忆

```bash
python3 src/laos.py \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR" \
  --task-json '{"type":"memory.create","input":{"type":"principle","title":"最少代码","scope":"global","workspace":"personal","confidentiality":"personal","source":"manual:user_confirmed","confidence":"confirmed","content":"使用尽可能少的代码实现相同功能。"}}'
```

该命令只创建 `candidate`。记录输出中的 `candidate_id` 后，使用 Review Gate 显式审核：

```bash
python3 src/laos.py \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR" \
  --task-json '{"type":"memory.review","workspace":"personal","input":{"action":"accept","candidate_id":"CANDIDATE_ID"}}'
```

work candidate 必须显式使用顶层 `"workspace":"work"`。workspace 或 project 不匹配时审核失败。

### 搜索和 Context Pack

```bash
python3 src/laos.py \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR" \
  --task-json '{"type":"memory.search","input":{"query":"最少代码","workspace":"personal"}}'
```

```bash
python3 src/laos.py \
  --root "$DATA_ROOT" \
  --state-dir "$STATE_DIR" \
  --task-json '{"type":"context.build","input":{"query":"最少代码","workspace":"personal"}}'
```

## 最终 `loop.coordinate` 示例

`loop.coordinate` 接收已经完成的任务证据；它不会执行 JSON 中描述的任务。

```bash
cat > /tmp/laos-loop-task.json /loop_engineering/runs//
```

可能包含：

```text
run.json
reflection.md
policy_suggestions.md
reflection_result.json
policy_candidates.json
policy_review.md
```

低风险 candidate generation 状态位于：

```text
/loop_engineering/generated_candidates/.json
```

这些文件是本地运行与审计产物，不是 active memory。

## 导入

ChatGPT 官方 ZIP 仅支持用户手动下载后本地导入：

```bash
python3 src/memory_tools.py import-chatgpt \
  --zip "$HOME/Downloads/chatgpt-export.zip" \
  --root "$DATA_ROOT" \
  --dry-run

python3 src/memory_tools.py import-chatgpt \
  --zip "$HOME/Downloads/chatgpt-export.zip" \
  --root "$DATA_ROOT"
```

手动文件导入：

```bash
python3 src/memory_tools.py import-manual \
  --path "$HOME/Downloads/note.txt" \
  --root "$DATA_ROOT" \
  --dry-run

python3 src/memory_tools.py import-manual \
  --path "$HOME/Downloads/note.txt" \
  --root "$DATA_ROOT"
```

PDF/DOCX 等二进制文件只归档 raw；当前不会进行深度结构化解析或全文索引。

## 本地验证

```bash
python3 -m unittest discover -s tests -v
python3 -m compileall -q src tests tools
git diff --check
git diff --cached --check
```

`v0.9.0` 的历史 Stage 17 macOS 集成与正式发布记录分别见 [Stage 17 最终整合审查](docs/progress/2026-07-05-stage-17-macos-final-integration-review.md)和 [v0.9.0 发布准备记录](docs/progress/2026-07-06-v0.9.0-release-preparation.md)。当前正式版本 `v0.10.0` 的记录见 [v0.10.0 发布准备记录](docs/progress/2026-07-11-v0.10.0-release-preparation.md)，其发布门禁结果为 **879 项通过 / 0 失败**。当前分支状态必须通过运行上述命令验证，不在说明文字中固定 SHA 或测试数量。

## 历史 v0.9.0 发布门禁

```text
Historical v0.9.0 release flow
→ Stage 17 local macOS integration review
→ commit documentation alignment
→ push feature branch
→ Draft PR macOS CI
→ human review
→ merge confirmation
→ v0.9.0 release preparation
→ v0.9.0 tag / GitHub Release confirmation
→ released
```

以上仅记录历史 `v0.9.0` 发布流程。本地验收、Draft PR、远程 CI、合并、tag 和正式 release 是不同 Gate；`v0.9.0` 的全部源码发布 Gate 已完成。后续代码变更继续按独立 PR 与 CI 门禁处理。

## 文档

- 当前阶段状态：`docs/PHASE_STATUS.json`
- 当前路线图：`docs/ROADMAP.md`
- macOS-first 决策：`docs/decisions/2026-07-05-macos-first-delivery-scope.md`
- v0.9 架构与安全审查：`docs/progress/2026-07-04-stage-15-v09-architecture-security-audit.md`
- v0.9 初始发布审查：`docs/progress/2026-07-04-stage-16-v09-release-review.md`
- v0.9.0 / Stage 17 历史 macOS 最终整合审查：`docs/progress/2026-07-05-stage-17-macos-final-integration-review.md`
- v0.9.0 正式发布记录：`docs/progress/2026-07-06-v0.9.0-release-preparation.md`
- v0.10.0 正式发布记录：`docs/progress/2026-07-11-v0.10.0-release-preparation.md`
- MCP checkpoint：`docs/mcp_checkpoint_validation.md`
- 自动更新 Loop：`docs/stage_07_2_real_loop_acceptance.md`
- Trusted Memory Loop：`docs/TRUSTED_MEMORY_LOOP.md`
- Schema：`schemas/`

## 许可证

MIT License。

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [l1871276598-dotcom](https://github.com/l1871276598-dotcom)
- **Source:** [l1871276598-dotcom/research-agent-memory](https://github.com/l1871276598-dotcom/research-agent-memory)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-l1871276598-dotcom-research-agent-memory
- Seller: https://agentstack.voostack.com/s/l1871276598-dotcom
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.