Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "tmcra-memory",
"displayName": "TMCRA Memory",
"version": "0.3.0-rc.10+claude.20260904",
"version": "1.0.0-rc.1+claude.20260906",
"description": "Auditable long-term memory recall and turn capture for Claude Code.",
"author": {
"name": "TMCRA",
Expand Down
7 changes: 2 additions & 5 deletions .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "tmcra-memory",
"version": "0.3.0-rc.10",
"version": "1.0.0-rc.1",
"description": "Automatic long-term memory recall and capture for Codex.",
"author": {
"name": "TMCRA",
Expand Down Expand Up @@ -29,10 +29,7 @@
],
"defaultPrompt": [
"Show the TMCRA memories that were injected for my latest completed answer.",
"Show which TMCRA memories are relevant to this task.",
"Remember this decision for future coding sessions.",
"Check whether the latest TMCRA memory write completed.",
"Show TMCRA installation and lifecycle status.",
"Open the memory control panel for this session.",
"Open TMCRA local Writer and background-organizer settings."
],
"brandColor": "#49E5C2",
Expand Down
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
* text=auto eol=lf
*.png binary
*.pt binary
runtime/** linguist-vendored -whitespace
16 changes: 15 additions & 1 deletion .github/workflows/hol-plugin-scanner.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,25 @@ jobs:
- name: Check out source
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: HOL Plugin Scanner
uses: hashgraph-online/ai-plugin-scanner-action@7e420247177d5beebbd3747ed16e4b29a1e41f57 # v1
uses: hashgraph-online/ai-plugin-scanner-action@d93c35b235ae854bcb181f2472f6d019619e8048 # v1; plugin-scanner 3.0.94
with:
plugin_dir: "."
mode: scan
min_score: 80
fail_on_severity: high
format: sarif
upload_sarif: true
install_cisco: true
- name: Show scanner findings even when the gate fails
if: always()
run: |
python - <<'PY'
import json
from pathlib import Path
path = Path("ai-plugin-scanner.sarif")
if path.is_file():
report = json.loads(path.read_text())
for run in report.get("runs", []):
for result in run.get("results", []):
print(json.dumps({key: result.get(key) for key in ("ruleId", "level", "message", "locations")}, ensure_ascii=True))
PY
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,6 @@ Thumbs.db
.tmcra/
scanner-report.*
release/
test-artifacts/
__pycache__/
*.py[cod]
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Changelog

## 1.0.0-rc.1 - 2026-09-06

- Add the redesigned memory workspace, local Writer/organizer settings, knowledge and graph views, session controls, task continuity, and bounded recall budgets.
- Require interactive host confirmation for conversational memory corrections; protect the correction discussion from automatic capture and replay.
- Add three pinned embedding/reranker profiles and Windows local-runtime preview controls. Local identity disables inherited cloud-provider task handoff.
- Preserve binary image bytes in release ZIPs and verify packaged assets against their sources.
- Bundle the verified backend, automatic private Python bootstrap and shared local identity discovery. `Install-Local.cmd` installs without TMCRA servers/accounts. Runtime files survive plugin-cache updates; stale cloud connections are blocked after local selection.
- Full-local acceptance remains partial: CPU ingest/raw recall passed; complex compilation timed out, with organizer and restart recovery still pending. Production is unchanged.

## 0.3.0-rc.10 - 2026-09-04

- Include the icon and overview image referenced by the Codex marketplace manifest in every release archive.
Expand Down
20 changes: 18 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
# TMCRA Memory for Codex

TMCRA Memory adds automatic long-term memory to Codex through the public TMCRA API. It does not require access to the TMCRA server.
TMCRA Memory adds automatic long-term memory to Codex through a local Memory API or the hosted TMCRA service. Windows local installation runs independently of TMCRA servers and accounts.

This repository is the standalone distribution mirror of the plugin maintained in the [TMCRA monorepo](https://github.com/reshuibuduo/tmcra/tree/main/07-tmcra-codex-plugins/tmcra-memory). Download the versioned ZIP and its SHA-256 file from [GitHub Releases](https://github.com/reshuibuduo/tmcra-plugin-codex/releases).

## What it does

Version 1.0.0-rc.1 adds session controls, task handoff, bounded evidence selection and a loopback memory control panel. See [the control contract and rollout checklist](docs/memory-controls.md). `tmcra_open_memory_center(session_id, project_path)` opens the panel; `tmcra_memory_control` exposes the same actions to explicit tools. Effective source corrections require the matching backend update, included in the local runtime.

- Initializes the global/project scope at `SessionStart` without recalling or injecting memory.
- Recalls relevant global and project memory only after `UserPromptSubmit`, using the current prompt as the query.
- Recalls relevant global and project memory after `UserPromptSubmit`; short continuations use the bound task objective and observed progress.
- Includes both user records (requirements and facts) and assistant records (Codex work progress and results) in recall, while keeping their actor and provenance labels separate.
- Applies authority in this order: current user instruction, historical user requirements/facts, then historical Codex progress/results. Assistant records never become user statements.
- Captures the completed user/assistant turn at `Stop`.
Expand All @@ -25,6 +27,12 @@ Codex Hooks do not expose a third-party custom side panel. The explicit inspecti

## Windows installation

For server-independent installation, extract the release ZIP and double-click **`Install-Local.cmd`**. It registers the plugin, installs a private Python runtime, downloads verified model files, creates a local identity, and starts the local memory service. No TMCRA account, API key or preinstalled Python is required. First-time dependency/model downloads require internet access. Restart Codex and review its nine Hooks when prompted; host consent remains yours. Windows x64 is supported; the light profile needs 16 GB RAM and approximately 6.3 GiB free at startup.

For the hosted service, use the account-based installer below.

Marketplace users can ask “Open TMCRA local installation”; `tmcra_open_local_install` opens the same workspace without login. Downloads begin after the user chooses and confirms a profile in the page.

Download the versioned release ZIP, verify the adjacent SHA-256 file, extract it to a stable local directory, then run:

```powershell
Expand Down Expand Up @@ -90,6 +98,14 @@ This is a repository snapshot, not reconstructed conversation history.

## Configuration

### Full-local Windows preview

The workspace offers three pinned embedding/reranker profiles: E5-small + multilingual MiniLM, BGE-M3 + BGE-reranker-v2-m3, and Qwen3-Embedding-4B + Qwen3-Reranker-0.6B.

The release and marketplace packages include the actual backend with a SHA-256 inventory. Use `Install-Local.cmd`, or run `node scripts/local_setup.mjs` from the plugin directory to open the installation page without login. Python and model files are downloaded automatically. The installer registers a private local selection; Codex, DSH and generic TMCRA MCP discover it after restarting their host. Existing cloud credentials remain stored, while stale cloud memory connections and background model requests are blocked after local selection. Failed setup keeps this local selection. Advanced `TMCRA_CONFIG_FILE` overrides must be cleared before automatic installation. A standalone [runtime package](https://github.com/reshuibuduo/tmcra/releases/tag/v1.0.0-rc.1) serves other MCP hosts.

Acceptance is partial: synthetic CPU ingest took 112 seconds and raw recall 0.52 seconds; complex compilation timed out at 600 seconds. Organizer and full-service restart recovery remain unverified. Lightweight startup requires approximately 6.3 GiB free memory. See the [acceptance record](https://github.com/reshuibuduo/tmcra/blob/v1.0.0-rc.1/docs/LOCAL_DEPLOYMENT_PREVIEW.zh-CN.md). A cloud-hosted agent can still send recalled evidence to its own model provider.

### Local Writer and background organizer

Ask Codex **“Open TMCRA local model settings”** to open the setup page. The MCP response contains no credential value or setup-session token. The page is served from a temporary random-token session bound to `127.0.0.1`, and it supports separate Writer and background-organizer providers or one shared provider.
Expand Down
32 changes: 31 additions & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,23 @@
# TMCRA Memory for Codex

TMCRA Memory 通过公开 TMCRA API Codex 提供自动长期记忆。普通用户无需服务器权限,也无需复制 API Key。此仓库是 [TMCRA 主仓库](https://github.com/reshuibuduo/tmcra/tree/main/07-tmcra-codex-plugins/tmcra-memory)中插件源码的独立发行镜像。
TMCRA Memory 通过本机 Memory API 或 TMCRA 托管服务为 Codex 提供自动长期记忆。Windows 本地安装独立于 TMCRA 服务器和账号。此仓库是 [TMCRA 主仓库](https://github.com/reshuibuduo/tmcra/tree/main/07-tmcra-codex-plugins/tmcra-memory)中插件源码的独立发行镜像。

[English](README.md)

## 1.0.0-rc.1 新增记忆控制

- 任务接续:短句“继续”使用当前绑定目标、最近结果和下一步;多个候选任务会要求明确选择。
- 可操作控制台:调用 `tmcra_open_memory_center`,传当前 `session_id` 和 `project_path`,可以查看任务、来源、写入状态,执行纠错、忽略与恢复。
- 统一工作台:集成记忆写入 / 后台整理 API 配置、知识库和知识图谱,支持来源追溯与范围筛选;密钥只在本机表单输入,保存后不回显。
- 聊天纠错:识别真实纠错意图后先暂停当前回合自动写入,核对来源与新内容,再请求宿主聊天确认。拒绝、取消、过期和缺少确认能力均不提交。
- 会话开关:`normal` 正常读写、`recall_only` 仅召回、`off` 关闭;恢复后不会补写关闭期间的回合。已经提交的远端写入不受此开关撤回。
- 召回预算:默认每轮 12000 字符,按完整证据块裁选;只对本轮重复和仍在宿主上下文中的相同证据去重。Token 用量为估计值。
- 有效纠错:需要同步部署服务端反馈接口更新。旧来源的召回会立即受控,新内容独立可搜索需要等待返回的索引任务完成。

任务与会话控制状态按服务地址、凭据指纹和项目隔离。切换登录凭据会创建独立的本机任务状态;跨应用已提交的长期记忆继续通过同一服务端项目 scope 共享。`TMCRA_MEMORY_STATE_DIR` 可显式指定多个本机适配器共用的状态目录。API Key 不会写入这个状态目录。

新增功能和部署验收说明见 [memory-controls.md](docs/memory-controls.md)。

## 核心能力

- `SessionStart` 初始化全局、项目和会话边界。
Expand All @@ -18,6 +32,12 @@ TMCRA Memory 通过公开 TMCRA API 为 Codex 提供自动长期记忆。普通

## 安装

**脱离 TMCRA 服务器:**下载 Release ZIP 并解压,双击 `Install-Local.cmd`。安装器自动注册插件、准备独立 Python、下载并校验模型、生成本机身份并启动记忆服务,无需 TMCRA 账号、API Key 或预装 Python。首次下载需要联网。完成后重启 Codex,并由你审核九项 Hook。当前支持 Windows x64;轻量档建议 16GB 内存,启动时约需 6.3GiB 空闲内存。

托管服务账号模式使用下面的安装方式。

从插件市场安装的用户,可直接说“打开 TMCRA 本地安装”,调用 `tmcra_open_local_install` 免账号打开同一工作台。选好档位并在页面确认后才开始下载安装。

从 [GitHub Releases](https://github.com/reshuibuduo/tmcra-plugin-codex/releases) 下载带版本号的 ZIP 和对应 SHA-256 文件。校验后解压到稳定目录。

Windows:
Expand All @@ -44,6 +64,16 @@ sh ./install.sh

## 本地 Writer 与后台整理模型

### 完整本地部署预览

工作台新增三档 embedding / reranker:E5-small + 多语言 MiniLM、BGE-M3 + BGE-reranker-v2-m3、Qwen3-Embedding-4B + Qwen3-Reranker-0.6B,以及安装、推荐、状态和启动/停止入口。

Release 和市场插件包均内置真实后端及 SHA-256 清单。使用 `Install-Local.cmd`,或在插件目录运行 `node scripts/local_setup.mjs`,即可免登录打开安装页。Python 与模型自动下载,身份自动生成并登记;重启宿主后 Codex、DSH 和通用 TMCRA MCP 自动发现本地连接。选择本地后,旧云端连接和后台云模型请求会被拦截;安装失败保留本地选择。原云端凭据保留在原位置。高级用户先清除显式 `TMCRA_CONFIG_FILE` 覆盖再进行自动安装。其他 MCP 宿主可使用[独立运行包](https://github.com/reshuibuduo/tmcra/releases/tag/v1.0.0-rc.1)。

完整验收仍在进行:CPU 合成写入 112 秒、原文召回 0.52 秒;复杂编译 600 秒超时,后台整理和完整重启恢复待测。轻量启动需约 6.3GiB 空闲内存。详见[验收记录](https://github.com/reshuibuduo/tmcra/blob/v1.0.0-rc.1/docs/LOCAL_DEPLOYMENT_PREVIEW.zh-CN.md)。宿主 Agent 使用云端主模型时,召回证据仍可能由宿主发往云端。

### 配置独立模型 API

在 Codex 中输入“打开 TMCRA 本地模型设置”即可打开配置页。MCP 返回结果不含 API Key 和页面会话令牌。配置页只监听 `127.0.0.1`,每次启动生成随机令牌;Writer 与后台整理可以共用模型,也可以分别填写 Provider、Base URL、模型名称和 API Key。

Codex 与 DeepSeek Harness 共用 `~/.config/tmcra/local-providers.json`。API Key 只保存在当前系统用户的本地文件中,测试连接时只发往用户填写的模型服务。Provider 或 Base URL 改变后必须重新填写 Key,已保存的 Key 不会转发到新地址。macOS/Linux 使用 `0600` 权限;Windows 移除继承 ACL,只授权当前用户与 SYSTEM。同一系统用户运行的其他进程仍可能读取该文件,因此这项功能适合可信的本地账号。
Expand Down
Binary file added assets/tmcra-logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading