rein

Multi-source cross-validated memory for AI agents

English | 中文

English

rein is a self-adaptive memory system for AI coding agents. It stores, recalls, and manages memories across sessions with embedding-based semantic dedup, data-driven decay (Kaplan-Meier survival curves), and a fully closed self-learning loop that replaces fixed parameters with learned values.

Current release: v0.28.9 (2026-05-06) — distribution-channels patch on v0.28.8. Adds Claude Desktop one-click install via DXT (.mcpb artifact, macOS Apple Silicon) with user_config-prompted GEMINI_API_KEY / REIN_DB / SUPERMEMORY_CC_API_KEY, and Claude Code plugin marketplace registration (/plugin marketplace add lyr1cs/rein). Build pipeline added at scripts/build-dxt.sh; manifest at dxt/manifest.json; plugin manifests at .claude-plugin/marketplace.json + plugins/rein/. New maintainer guide at docs/guides/dxt-build.md; ADR at docs/decisions/distribution-channels.md. End-user install steps in docs/manual/02-installation.md. No runtime behavior changes from v0.28.8 — binary is bit-identical to v0.28.8 with the version field bumped. Tests / clippy / fmt status unchanged from v0.28.8 (1462 / 0 / 3 ignored / 0 / 0). License: AGPL-3.0-or-later. See Recent releases below for the v0.21 → v0.28.9 progression.

Previous release: v0.28.8 (2026-05-04) — second-pass audit hardening on v0.28.7. Closed 15 P2 + 1 P3 findings across 17 codex review rounds (2-consecutive-clean saturation at R16/R17). Headline fixes: M-8 cluster-bucket alignment (learn-time top_vec_hit_cluster now uses memory-id-remap against current memory_clusters), L6 LRU fallback preservation (learned_shadow_fusion cap eviction restricted to cluster-scoped buckets), ars_parameter_policy schema robustness (peek schema_version before typed deserialize, schema-aware COALESCE default, BEGIN IMMEDIATE wrapping in repair_corrupt_parameter_policy). Plus M-1 persistence-side per-surface scalar split, M-5 synthesis/concept-summary threshold rollback, M-6 outer simplex↔legacy blend, L1 bootstrap_priors sanitize cap, L4 auth-policy locks, L5+L7 doctor recovery + release-gate test coverage. Default-OFF behavior bit-identical to v0.28.7.

For the full GitHub-ready manual, see docs/manual/README.md. Reference tables live under docs/reference/.

Features

Installation

Three install paths depending on your client:

Install on Claude Desktop (DXT — macOS Apple Silicon)

rein ships as a Claude Desktop Extension (.mcpb). One-click install,
no Rust toolchain required.

1. Download rein-v0.28.9.mcpb from
   Releases.

2. Clear macOS quarantine (one-time, the build is unsigned):

   xattr -d com.apple.quarantine ~/Downloads/rein-v0.28.9.mcpb
   

3. Double-click the file. Claude Desktop opens its install dialog.

4. Fill in Gemini API Key (required); leave Memory database path and
   Supermemory API Key blank to use defaults.

5. Click Install. Claude Desktop spawns rein serve over stdio. ~40
   rein_* tools appear in your next chat.

For step-by-step including upgrade, uninstall, and troubleshooting, see
docs/manual/02-installation.md → Claude Desktop.
For maintainers, the build pipeline is documented in
docs/guides/dxt-build.md.

Other platforms (Intel Mac / Linux / Windows): the DXT bundle is
macOS Apple Silicon only. Use the
Claude Code plugin marketplace
path or cargo install instead.

Install via Claude Code plugin marketplace

/plugin marketplace add lyr1cs/rein
/plugin install rein@rein

The plugin registers the rein MCP server entry in Claude Code. You still
need the rein binary on your PATH:

cargo install --git https://github.com/lyr1cs/rein --locked rein
# or download a release binary and put it in $PATH

Then set GEMINI_API_KEY in your shell environment or ~/.rein/config.toml.
See docs/manual/02-installation.md for
full configuration.

From source

git clone https://github.com/lyr1cs/rein.git
cd rein

# Standard build (CLI + MCP server only)
cargo install --path crates/rein --locked

# Full build with Neural Wiki GUI (recommended)
cd crates/rein/gui && npm ci && npm run build && cd ../../..
cargo install --path crates/rein --locked --features gui

Or use the install script:

./scripts/install.sh

The install script builds the embedded GUI by default when npm is available. Set REIN_INSTALL_GUI=0 for a CLI-only install.

Prerequisites

• Rust toolchain (1.75+)
• Node.js + npm (for GUI builds or the default install script path)
• A Gemini API key (free tier: 1500 req/day)

GUI Service Management

# Start GUI server in background (listens on :8680)
rein gui on

# Stop GUI server
rein gui off

# Or run in foreground with MCP + GUI
rein serve --gui

# Open in browser
open http://localhost:8680

The GUI requires building with --features gui. Without it, the gui subcommand is available but serves no embedded assets.

Quick Start

# 1. Set your API key
export GEMINI_API_KEY="your-key-here"

# 2. Auto-configure all detected MCP clients
rein init

# 3. Start the MCP server (usually done by your client)
rein serve

CLI Reference

How Cleanup Works (Provenance-Preserving)

rein's cleanup pipeline is provenance-preserving: it never hard-deletes information. The process has three stages:

1. Consolidation — Groups topic variants (e.g., Docker Deployment / docker-deployment) and merges all memories within each group into a single high-quality canonical memory. Source memories become evidence records in the memory_evidence table, preserving their original content, timestamps, and keywords.

2. Dedup — Scans for content-level duplicates within each topic group using lexical similarity (Jaccard + containment) and optionally embedding cosine similarity. Matches above threshold are merged into the winner; the loser's unique lines are appended with provenance markers ([merged from <id> on <date>]) and the loser is recorded as evidence.

3. Adaptive refresh — After consolidation and dedup, the adaptive engine (M1-M6) runs: HDBSCAN re-clusters, survival curves rebuild, tier boundaries update, and alpha/threshold learning processes new events.

Every merge decision is logged in the dedup_decisions append-only ledger with winner/loser IDs, scores, relation type, confidence, and operator. This is rein's equivalent of Git's reflog — you can always trace how a canonical memory was formed.

# Preview what cleanup would do (safe)
rein cleanup --all --dry-run

# Run cleanup on a specific topic
rein cleanup "docker-deployment"

# Full store cleanup
rein cleanup --all

# Run cleanup through the worker entrypoint
rein worker cleanup --all

consolidate keeps the old rein consolidate <topic> -s "summary" flow, but also supports:

• --topics a,b,c to batch a named topic set
• --pattern 'rmcp*' to batch by glob
• --all to process every topic
• --merge-variants to group case/space/hyphen variants such as Docker Deployment / docker-deployment
• omitting --summary to let rein auto-generate a consolidated memory, using the configured LLM when available and a local fallback otherwise

Batch consolidation fans out LLM synthesis asynchronously and in parallel, then commits SQLite writes sequentially. Cleanup actions also emit adaptive feedback and refresh M1-M6 state after the batch completes.

Cleanup is now scoped-first:

• rein cleanup X, rein cleanup --topics ..., or rein cleanup --pattern ... only deduplicates the selected groups
• destructive full-store cleanup requires rein cleanup --all
• rein cleanup --dry-run previews the scope
• background-style cleanup is handled by rein worker cleanup ..., rein worker cleanup-queue, and the cleanup queue worker

Store-time gray-zone dedup now also uses a dedicated async queue:

• hot-path store creates the new memory without blocking on remote LLM verdicts
• a dedup-queue worker later resolves gray-zone pairs with structured LLM verdicts
• you can drain it manually with rein worker dedup-queue

Recall is now evidence-aware:

• canonical memories are ranked with support_count and source_diversity
• recall output includes lightweight evidence_preview
• rein evidence <canonical_id> or /api/memories/:id expands the full evidence list
• lower-confidence / lower-corroboration results can use evidence second-stage rerank

Adaptive learning now sees richer canonical signals:

• reranker learning uses support / diversity features
• alpha optimization uses KG / episode / support / diversity-aware candidate scoring
• Adaptive GUI surfaces cluster-level dedup / admission / promotion decisions

CJK dedup now uses a hybrid lexical strategy:

• jieba-rs adds Chinese word segmentation
• character bigrams remain enabled as a fallback for CJK and mixed technical text
• both token streams are combined before Jaccard / containment scoring

More detailed docs:

• docs/guides/canonical-read-model.md
• docs/guides/evidence-aware-recall.md
• docs/reference/adaptive-learning-signals.md

Audit / handoff commit chain:

• 8b9e747
• b358100
• b861a4f
• 1b0765a
• 45de919
• d92170a
• d7200b3

Operator inspection commands:

• rein canonicals shows canonical memories and their support/merge counters
• rein evidence <canonical_id> shows absorbed evidence snapshots
• rein dedup-log shows the recent dedup ledger

MCP Tools

When running as an MCP server (rein serve), Rein exposes 40 production MCP
tools through the operation inventory. The authoritative list is maintained in
docs/reference/mcp-tools.md, grouped as:

• Core memory: store, recall, update, forget, recent, topics, canonicals,
  evidence, stats, and health.
• Maintenance: GC, dedup, concept dedup, organize, consolidate, cleanup,
  resummerize, and archive summary refresh.
• Knowledge graph and temporal: memoir tools, concept state, concept summary
  refresh, timeline, and concept history.
• Adaptive, session, ARS, and judge: feedback, adaptive status, session ingest,
  synthesis judge, and concept-summary judge.

Knowledge Graph Relation Types

part_of, depends_on, related_to, contradicts, refines, alternative_to, caused_by, instance_of, superseded_by

LLM Extraction (v0.3)

rein uses LLM (Gemini 3.1 Flash Lite or local models via OMLX) for structured memory extraction. The hook system automatically builds a knowledge graph from coding sessions.

Architecture:

• hook_post — local pattern extraction (crash safety net) + buffer to session file
• hook_compact — record compact context for async extraction
• hook_stop — queue full session distillation: memories + concepts + links + episode summary
• hook_session_start / hook_prompt — optional Codex additionalContext injection from Rein's working surfaces
• hook_pre_tool_use / hook_permission_request — deny-only Codex guardrails for obviously destructive shell commands

Upgrade old memories:

rein upgrade --dry-run    # preview
rein upgrade              # convert all old memories to knowledge graph
rein upgrade --topic debug  # convert specific topic only

Configuration:

[extract]
provider = "google"    # or "omlx" or "none"

[extract.google]
model = "gemini-3.1-flash-lite-preview"
max_input_chars = 0    # 0 = no truncation (1M token model)

[extract.omlx]
endpoint = "http://localhost:11434/v1"  # Ollama, LM Studio, vLLM, etc.
model = "default"
max_input_chars = 16000

Self-Learning Quality System (v0.3.0)

rein automatically learns which memories are useful and which are noise, without human parameter tuning.

How it works:

1. LLM assigns quality_confidence (0-1) at extraction time — zero extra API cost
2. System tracks recall-then-access patterns to classify memories as "good" (used) or "bad" (recalled but unused)
3. Feature weights auto-adjust from data: utility, novelty, connectivity, recency
4. Adaptive admission threshold rises when recent quality is low, relaxes when high
5. GC prunes low-quality concepts whose source memories are recalled 5+ times but never accessed

No manual tuning needed — cold-starts with LLM judgment, data gradually takes over.

Based on: ICLR 2026 Admission Control, PropMem (Prosus), FActScore, MACLA Bayesian posteriors.

Canonical-First Recall

rein now treats canonical memories as the default read model:

• store-time dedup tries to merge gray-zone writes into an existing canonical when evidence already exists
• admission/novelty scoring uses the current canonical view, not raw topic fragments
• working-set and always-on surfaces are refreshed from persisted canonical memories
• recall returns canonical memories by default, with evidence_preview for absorbed observations
• detail endpoints and GUI panels expand the full supporting evidence on demand

For API compatibility, GET /api/memories/:id returns the legacy top-level memory fields and also includes:

• memory: the canonical memory payload
• evidence: supporting evidence snapshots

Temporal Knowledge Graph (v0.4.0)

rein now tracks when knowledge changes, not just what the current state is. Inspired by Zep/Graphiti 2025.

Capabilities:

• Concept revision history — every refine_concept auto-snapshots the old state before overwriting
• Episode nodes — each session creates an Episode linking to concepts and memories touched
• Temporal link validity — ConceptLink has valid_from/valid_until windows; expired links are skipped in BFS
• Contradiction detection — when a new definition differs significantly (sim < 0.3), old outgoing links are expired
• Temporal recall — rein_recall supports from/to date params for time-range filtering
• Timeline view — rein_timeline shows chronological events (episodes, concept changes, memory creation)
• Concept history — rein_concept_history shows how a concept's definition evolved over time

Example queries enabled:

• "What changed last week?" → rein_timeline --from 2026-03-19 --to 2026-03-26
• "When did concept X change?" → rein_concept_history --memoir rust --name ownership
• "What did I know about Y before March?" → rein_recall "Y" --to 2026-03-01

Autonomous Retrieval Routing (v0.4.0)

rein automatically classifies queries and routes them to the optimal search strategy — no configuration needed.

Classification is rule-based (zero LLM calls, sub-microsecond). MCP responses include [route: type] prefix for transparency. TA-Mem 2026 and MemR3 2025 are tracked as related memory-retrieval background, not as implemented retrieval controllers.

Adaptive Engine (v0.6.0+)

rein's core philosophy is to minimize fixed parameters through data-driven adaptation. Bootstrap defaults still exist for cold start and safety, but the adaptive engine moves fusion, decay, tiering, and threshold behavior toward observed feedback in the slow channel.

Pipeline: M4 → A1 → M3 → M5 → M2 → M6

Also:

• Embedding-based semantic dedup in GC slow channel (catches paraphrases Jaccard misses)
• Provenance-preserving merge — temporal anchors and unique details never lost
• Snapshot CAS — adaptive state saved with read-merge-write on version conflict

Recent releases

The v0.21 → v0.28.8 arc rebuilt rein around three axes: a unified operation registry, an adaptive read-side synthesis (ARS) stack with feedback-driven gates, and end-to-end audit-cycle hardening of every adaptive surface.

v0.28.8 keeps the v0.28.7 default surface unchanged: only [ars.acceleration] ships default-on (still fail-closed — learned parameters do not affect runtime until a healthy ars_parameter_policy promotes a canary with positive scoped adoption weights). The runtime LLM judge ([ars.llm_judge]) and its nightly_cron remain default-off per the v0.28 charter Non-Goal — operators must explicitly opt in (incurs LLM API spend). ARS content-generation features ([ars].concept_summary_enabled, recall_synthesis_enabled, cold_archive_enabled) and [resummerize].enabled remain operator-controlled.

Architecture Diagrams

Memory Storage Flow

flowchart TD
    A[Input text / tool output] --> B[hook_post or rein_store]
    B --> C[LLM Extraction\nGemini Flash Lite / OMLX]
    C -->|LLM unavailable| D[Rule-based fallback\ntopic · summary · keywords · importance]
    C --> D2[postprocess\ndate detection · preference tagging]
    D --> D2
    D2 --> E{store_with_dedup\nBEGIN IMMEDIATE}
    E -->|sim ≥ cluster_threshold A1| F[Provenance-preserving merge\nloser → evidence record]
    E -->|sim in gray-zone| G[LLM dedup verdict\nasync dedup-queue]
    E -->|new memory| H[INSERT memories]
    H --> I[auto_link\nbidirectional related_ids]
    I --> J[evolve\nknowledge evolution]
    J --> K[HNSW + Tantivy index update\nfire-and-forget]
    K --> L[needs_vec_dedup flag\nfor GC slow-channel embedding dedup]
    F --> M[dedup_decisions ledger]
    G --> M

Recall Pipeline

flowchart TD
    Q[Query] --> CL[Query Classifier\n6 strategies · rule-based · 0 LLM calls]
    CL -->|strategy + alpha| EX[Query Expansion\nGemini / OMLX → 2-3 variants]
    EX --> P1[Channel 1: Tantivy BM25\nlocal · <1ms]
    EX --> P2[Channel 2: HNSW vector\nlocal ~5ms / Gemini API ~255ms]
    EX --> P3[Channel 3: KG FTS + BFS\nconcept land-and-expand]
    P1 --> FU[RRF / CC Fusion\nlearned alpha M2]
    P2 --> FU
    P3 --> FU
    FU --> TF[M5 Tier Filter\nCold excluded for non-Exploratory]
    TF --> SW[Strength Weighting\nper-cluster KM curve M3 → global prior → Ebbinghaus]
    SW --> RF[Multi-feature Rerank\n8 features · learned weights]
    RF -->|optional| LR[LLM Reranker\nGemini / OMLX · strong-signal bypass]
    RF --> CC[Canonical-first collapse\nevidence_preview attached]
    LR --> CC
    CC --> CV[Cross-validate\nSupermemory + auto-memory files]
    CV --> RES[Final results\nconfidence 95%/85%/62% by source count]

Compression (PreCompact Hook)

flowchart TD
    T[PreCompact trigger\nContext window approaching limit] --> HC[hook_compact\nrecord compact context]
    HC --> SB[Read session buffer\naccumulated tool outputs + turns]
    SB --> LE[LLM extraction\nmemories + concepts + links]
    LE --> WQ[Async memory queue\n~/.rein/memory_queue_<project>.jsonl]
    WQ --> BW[Background worker\nrein worker memory]
    BW --> SD[store_with_dedup\nper-memory dedup + merge]
    SD --> EP[Episode node created\nsession → concept_ids + memory_ids]
    EP --> TL[ConceptLink temporal validity updated\nvalid_from / valid_until]
    TL --> CL[Session buffer cleared\nready for next context window]

    style T fill:#f96,color:#000
    style EP fill:#6af,color:#000

Configuration

rein loads configuration with the following priority (highest wins):

1. Environment variables
2. TOML config file ($REIN_CONFIG or ~/.config/rein/config.toml)
3. Compiled-in defaults

Environment Variables

config.toml

[database]
path = "auto"                          # "auto" = ~/.rein/memories.db

[embedding]
provider = "google"    # or "omlx" or "none"
dimensions = 3072

[embedding.google]
model = "gemini-embedding-001"

[embedding.omlx]
endpoint = "http://localhost:8000/v1"
model = "default"

[search]
rrf_k = 60.0
rrf_fts_weight = 0.3
rrf_vec_weight = 0.7
fusion_method = "rrf"      # or "cc" (Convex Combination, Bruch 2023)
cc_alpha = 0.5             # CC blend: alpha * sparse + (1-alpha) * dense

dedup_similarity = 0.70    # uses max(jaccard, containment) similarity
dedup_time_window_days = 7

[chunking]
max_tokens = 512
overlap_percent = 10
metadata_prefix = true

[sync]
supermemory_enabled = true
auto_memory_enabled = true
auto_memory_glob = "~/.claude/projects/*/memory/**/*.md"

[decay]
base_lambda = 0.06
ltm_beta = 0.8
stm_beta = 1.2
interval_hours = 24
prune_threshold = 0.05
stm_to_ltm_access_count = 5

[server]
compact = false
sse_enabled = false
sse_port = 8680
sse_bind = "127.0.0.1"

Database

The database is stored at ~/.rein/memories.db by default. rein auto-migrates from the old location if needed.

Override with the REIN_DB environment variable or the [database] path config key.

Hook Setup for Claude Code

Add the following to your Claude Code settings.json to enable automatic memory extraction:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "rein hook post", "timeout": 10 }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "rein hook compact", "timeout": 10 }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "rein hook stop", "timeout": 30 }
        ]
      }
    ]
  }
}

Hook behavior:

• PostToolUse -- local pattern extraction (crash safety net) + buffers for session-end batch processing
• PreCompact -- records compact context for the async memory pipeline
• Stop -- queues full knowledge extraction: memories + concepts + links + episode summary via async worker

Hook Setup for Codex CLI

Codex CLI hooks require codex_hooks = true and either ~/.codex/hooks.json
or inline [hooks] tables in ~/.codex/config.toml.

rein init now configures the Codex MCP entry and installs the Rein hooks:

[features]
codex_hooks = true

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "REIN_AGENT_LABEL=codex rein hook session-start", "timeout": 5 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "REIN_AGENT_LABEL=codex rein hook pre", "timeout": 5 }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "REIN_AGENT_LABEL=codex rein hook permission", "timeout": 5 }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "REIN_AGENT_LABEL=codex rein hook post", "timeout": 10 }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "REIN_AGENT_LABEL=codex rein hook prompt", "timeout": 5 }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "REIN_AGENT_LABEL=codex rein hook stop", "timeout": 30 }
        ]
      }
    ]
  }
}

The Codex hook payload differs from Claude Code's payload. Rein understands the
official Codex fields (hook_event_name, tool_input, tool_response,
prompt, last_assistant_message, and transcript_path). PostToolUse and
Stop feed the same async memory pipeline used by Claude Code hooks.
PreToolUse and PermissionRequest are deny-only guardrails. SessionStart
and UserPromptSubmit can emit official Codex additionalContext JSON when
explicitly enabled:

[hooks.codex]
inject_prompt_context = true
inject_session_context = true
max_additional_context_chars = 4000

Remote Access via HTTP/SSE

Start rein with SSE transport for remote or multi-client access:

rein serve --sse

By default, the server binds to 127.0.0.1:8680.

To bind to a non-localhost address, you must set the REIN_HTTP_TOKEN environment variable for bearer token authentication:

export REIN_HTTP_TOKEN="your-secret-token"

Configure bind address and port in config.toml:

[server]
sse_enabled = true
sse_port = 8680
sse_bind = "0.0.0.0"    # requires REIN_HTTP_TOKEN

Transparent Proxy (v0.10.0)

rein can run as a transparent HTTP proxy that records LLM conversations without modifying requests. This works with any agent that supports base URL override.

Quick Start

# 1. Start the proxy (background)
rein serve --proxy &

# 2. Use with your agent
ANTHROPIC_BASE_URL=http://127.0.0.1:8690 claude       # Claude Code
codex -c 'model_providers.rein_proxy={ name = "Rein Proxy", base_url = "http://127.0.0.1:8690/v1", env_key = "OPENAI_API_KEY", wire_api = "responses", supports_websockets = false, env_http_headers = { "x-rein-token" = "REIN_PROXY_TOKEN" } }' -c 'model_provider="rein_proxy"'

Shell Aliases (recommended)

Add to ~/.zshrc or ~/.bashrc for convenience:

alias rein-proxy="rein serve --proxy &"
claudep() { REIN_PROXY_ACTIVE=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8690 ANTHROPIC_CUSTOM_HEADERS="x-rein-token: ${REIN_PROXY_TOKEN:-}" claude "$@"; }
codexp() { REIN_PROXY_ACTIVE=1 codex -c 'model_providers.rein_proxy={ name = "Rein Proxy", base_url = "http://127.0.0.1:8690/v1", env_key = "OPENAI_API_KEY", wire_api = "responses", supports_websockets = false, env_http_headers = { "x-rein-token" = "REIN_PROXY_TOKEN" } }' -c 'model_provider="rein_proxy"' "$@"; }
codexsubp() { REIN_PROXY_ACTIVE=1 codex -c 'model_providers.rein_sub_proxy={ name = "Rein Subscription Proxy", base_url = "http://127.0.0.1:8690", requires_openai_auth = true, wire_api = "responses", supports_websockets = false }' -c 'model_provider="rein_sub_proxy"' -c 'chatgpt_base_url="http://127.0.0.1:8690/backend-api"' "$@"; }
codexsubpws() { REIN_PROXY_ACTIVE=1 codex -c 'model_providers.rein_sub_proxy_ws={ name = "Rein Subscription Proxy WS", base_url = "http://127.0.0.1:8690", requires_openai_auth = true, wire_api = "responses", supports_websockets = true }' -c 'model_provider="rein_sub_proxy_ws"' -c 'chatgpt_base_url="http://127.0.0.1:8690/backend-api"' "$@"; }

Then: rein-proxy to start, claudep, codexp, codexsubp, or codexsubpws to use. For ChatGPT-login Codex, codexsubp remains the recommended loopback entrypoint; smoke it with ./scripts/smoke_codexsubp.sh. For the websocket-enabled path, use codexsubpws or ./scripts/smoke_codexsubp_ws.sh.
The codexsubp/codexsubpws provider overrides are generated from scripts/codexsubp_provider.toml.tmpl, which is the single source of truth for requires_openai_auth = true.

Codex CLI Config (alternative)

Configure Codex CLI permanently in ~/.codex/config.toml using a custom provider:

[model_providers.rein_proxy]
name = "Rein Proxy"
base_url = "http://127.0.0.1:8690/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
supports_websockets = false
env_http_headers = { "x-rein-token" = "REIN_PROXY_TOKEN" }

model_provider = "rein_proxy"

This makes all Codex calls go through the rein proxy by default (requires proxy to be running).

Supported Agents

Note: Codex subscription/OAuth login proxying is not the same as the API-key Responses API proxy above. For API-key Codex, keep using codexp. For ChatGPT-login Codex, codexsubp is still the recommended loopback entrypoint today: it keeps requires_openai_auth = true, points chatgpt_base_url at the local rein proxy, and disables websocket transport so the first-party backend stays on the local record-only path. rein now also has an experimental websocket-enabled path (codexsubpws / smoke_codexsubp_ws.sh) that starts with websocket transport and relies on local 426 Upgrade Required fallback when upstream websocket is unavailable.

For ChatGPT-login Codex on loopback, codexsubp is the practical path today. It uses a custom provider with requires_openai_auth = true so Codex still uses ChatGPT login, but the provider itself points to the local rein proxy and disables websocket transport. chatgpt_base_url is also pointed at the local proxy so helper/discovery traffic (/wham/*, /connectors/*, /v1/agent/register, etc.) follows the same path. This keeps the subscription-login flow working over HTTP while the broader websocket and matrix automation work is hardened.
Even when a client attempts websocket upgrade directly, rein only upgrades the structured-text /responses path; non-/responses first-party routes stay on ordinary HTTP and retain their artifact-mirror-only behavior.

How it works

• Proxy intercepts /v1/messages (Anthropic), /v1/chat/completions (OpenAI), /responses / /v1/responses (Codex / OpenAI Responses API), transparently forwards /backend-api/codex/* (Codex first-party backend), and routes ChatGPT helper/discovery paths such as /wham/*, /connectors/*, /v1/agent/register, /authenticate_app_v2, and /codex/safety/arc to the ChatGPT backend root
• Requests are forwarded unmodified (record-only, no injection)
• Assistant responses are asynchronously extracted and stored as memories on the standard public path and on first-party Codex /responses; other first-party routes stay artifact-mirror-only and are mirrored as raw artifacts without structured extraction
• SSE streaming is passed through byte-for-byte with zero latency impact
• Dedicated blocking thread with resident SqliteStore for extraction
• Other endpoints (e.g. /v1/models) are passed through unmodified

Configuration

[proxy]
port = 8690
bind = "127.0.0.1"
anthropic_upstream = "https://api.anthropic.com"
openai_upstream = "https://api.openai.com"
chatgpt_upstream = "https://chatgpt.com/backend-api"
codex_upstream = "https://chatgpt.com/backend-api"
extract_enabled = true    # record memories from responses
store_min_chars = 220     # skip short responses
store_min_score = 3       # quality threshold for extraction

Security: Non-localhost binds require REIN_PROXY_TOKEN. Auth headers are forwarded opaquely and never logged.

Async Memory Pipeline (v0.10.0)

Memory extraction is now fully asynchronous. Hooks queue jobs to a file-based queue, and a background worker processes them with LLM extraction, dedup, and persistence.

# Manually drain the queue (usually automatic via spawn)
rein worker memory

Architecture:

• hook_post / hook_compact / hook_stop queue jobs to ~/.rein/memory_queue_<project>.jsonl
• Background worker (rein worker memory) processes jobs with exponential backoff and dead-lettering
• Cross-session dedup via fingerprint + content similarity
• Working set — project-scoped memory surface updated on each extraction
• Always-on index — stable, high-quality summaries for project-level context

Configuration:

[async_memory]
max_retries = 3
base_backoff_ms = 2000
max_jobs_per_run = 32
batch_size = 8
spawn_cooldown_ms = 1500
max_working_set_items = 40
max_always_on_items = 24

Neural Wiki GUI (v0.11.0)

rein includes a built-in web GUI for visual exploration of your memory system. The GUI is embedded in the binary via rust-embed — no separate web server needed.

Quick Start

# Build with GUI support
cd crates/rein/gui && npm ci && npm run build && cd ../../..
cargo install --path crates/rein --locked --features gui

# Start the server with GUI enabled (implies --sse)
rein serve --gui

# Open in browser
open http://localhost:8680

The GUI is available at http://localhost:8680/ when running with --gui. API endpoints are at /api/* and MCP at /mcp.

Pages

Authentication

API endpoints (/api/*, /mcp) require a bearer token when REIN_HTTP_TOKEN is set. The GUI itself is served without auth so the SPA can bootstrap and show a token input dialog. Set the token in the Settings page.

Configuration

[server]
gui_enabled = false    # enable GUI (or use --gui flag)
sse_port = 8680        # port for HTTP/SSE/GUI
sse_bind = "127.0.0.1" # bind address

Development

The frontend source lives in gui/ (React 18 + TypeScript + Tailwind + Vite).

cd gui
npm install
npm run dev    # Dev server at localhost:5173, proxies API to localhost:8680
npm run build  # Build to gui/dist/ (embedded by rust-embed at compile time)

Architecture

flowchart TD
    U[User / AI Agent]
    CLI[CLI\n20+ commands]
    MCP[MCP Server\n39 tools · stdio / HTTP / SSE]
    GUI[Neural Wiki GUI\nReact + Tailwind]
    PXY[Proxy\nClaude · Codex subscription · record-only]

    U --> CLI
    U --> MCP
    U --> GUI
    U --> PXY

    CORE[rein core]
    CLI --> CORE
    MCP --> CORE
    GUI -->|inventory-backed REST API| CORE
    PXY -.->|async queue| CORE

    REC[Recall Pipeline\n3-channel + RRF/CC + rerank + canonical-first]
    ST[Store · Dedup · Evolve\nauto-link · provenance-preserving merge]
    HK[Hooks\npost · compact · stop]
    ADP[Adaptive Engine\nM1-M6 + A1]
    KG[Knowledge Graph\nmemoir · concept · episode · temporal links]

    CORE --> REC
    CORE --> ST
    CORE --> HK
    CORE --> ADP
    CORE --> KG

    DB[(SQLite memories.db\nmemories · FTS5 · sqlite-vec)]
    TN[Tantivy BM25 side index]
    US[usearch HNSW side index]

    REC --> DB
    ST --> DB
    HK --> ST
    ADP --> DB
    KG --> DB

    ST -.fire-and-forget.-> TN
    ST -.fire-and-forget.-> US
    REC -.reads.-> TN
    REC -.reads.-> US

    style DB fill:#6af,color:#000
    style CORE fill:#f96,color:#000

Storage is the single source of truth (memories.db): SQLite with FTS5 + sqlite-vec. Tantivy and usearch side indexes are derived, auto-rebuilt, and queried by the recall pipeline — storage writes update them fire-and-forget so hot-path latency stays unaffected.

Search Pipeline

Two independent search paths run in parallel, then merge:

Text path:

1. Tantivy BM25 -- full-text search with BM25 ranking (falls back to FTS5 if Tantivy unavailable)

Vector path:
2. Cache check -- look up query embedding in local cache (keyed by model + query)
3. HNSW search -- O(log n) approximate nearest neighbor via usearch (falls back to sqlite-vec)
4. If cache miss: Embed API -- call Google gemini-embedding-001 or OMLX, cache result, then HNSW search

Merge:
5. RRF/CC fusion -- Reciprocal Rank Fusion or Convex Combination merges text + vector results (path quality gating excludes empty paths)
6. Adaptive scoring -- Per-cluster Kaplan-Meier survival curves (or Ebbinghaus cold-start fallback) weight final ranking + temporal filtering
7. Cross-validation -- compare with Supermemory + auto-memory results, assign confidence

Embedding Backends

rein uses an EmbedderKind enum dispatch to support multiple embedding backends:

• Google (gemini-embedding-001) -- default, 3072 dimensions; provider benchmark details are documented in docs/reference/bibliography.md
• OMLX -- local embedding via OpenAI-compatible API endpoint

Set [embedding] provider to "google", "omlx", or "none" in config.

Proxy / Endpoint Override

For users in China or behind firewalls, all API endpoints are configurable:

Direct proxy (Cloudflare Worker, Nginx reverse proxy):

[embedding.google]
endpoint = "https://your-gemini-proxy.com"
# Requests: {endpoint}/v1beta/models/gemini-embedding-001:embedContent

[sync]
endpoint = "https://your-supermemory-proxy.com"

OpenRouter or other OpenAI-compatible aggregators:

[embedding]
provider = "omlx"

[embedding.omlx]
endpoint = "https://openrouter.ai/api/v1"
model = "google/gemini-embedding-001"

This works because the OMLX backend uses the OpenAI /v1/embeddings format, which is compatible with OpenRouter, LiteLLM, and similar services.

Memory Decay Model

• Critical memories never decay (strength = 1.0 forever)
• STM (Short-Term Memory): faster decay (beta = 1.2), promoted to LTM via cluster survival curve (fallback: 5 accesses)
• LTM (Long-Term Memory): slower decay (beta = 0.8), assigned to high / critical importance
• Access count slows decay: lambda_eff = lambda / (1 + access_count * 0.2)

Supported Clients

rein init auto-detects and configures:

• Claude Code
• Claude Desktop
• Cursor
• Windsurf
• VS Code (Copilot)
• Gemini CLI
• Codex
• OpenCode

Performance Targets

Cost Estimate

License

Copyright (C) 2026 Eric Lee. All rights reserved except as licensed under AGPL-3.0-or-later.

AGPL-3.0-or-later — see LICENSE.

rein is a server (MCP / REST / GUI). The AGPL §13 network-use clause means: if you run a modified version of rein as a service that users interact with over a network, you must provide those users access to the modified source code. Self-hosted personal use, internal-only deployment within your organization, and integrations that talk to rein over its public API (Claude Code, Cursor, IDE plugins, etc.) are all unaffected.

If you need a non-AGPL license for commercial / proprietary use, the project's copyright holder (Eric Lee) retains the right to dual-license — open an issue.

中文

项目简介

rein 是一个自适应记忆系统，专为 AI 编程智能体设计。它跨会话存储、检索和管理记忆，通过反馈事件和慢通道学习逐步减少固定参数。

当前版本：v0.28.8（2026-05-04）— v0.28.7 之上的二轮 audit 加固。17 轮 codex review（R1–R17）跑到 2-consecutive-clean 饱和。共关闭 15 P2 + 1 P3，全程 0 P1。重点：M-8 cluster bucket 对齐 — 学习时 top_vec_hit_cluster 改用 memory-id remap 查 memory_clusters，修掉 R13 发现的 M4-然后-M2 正常流水线顺序使 cluster_version_at_recall 对每个 event 都失效的常态 bug。L6 fallback 保护 — learned_shadow_fusion 的 LRU 驱逐限定在 cluster-scoped 桶（{query_type}:{cluster_id} 形状，由 is_cluster_scoped_bucket 谓词识别），保证高 cardinality 下 global 与 per-query-type fallback 链不被静默驱逐。ars_parameter_policy schema 健壮性 — typed deserialize 之前先 peek schema_version（R8 修 future-schema 被误判 Corrupt 后被 doctor --fix 删除）、CAS predicate 用 schema-aware COALESCE 默认值（R8）、用 > 而非 != 决定 future-schema 保护（R15）、repair_corrupt_parameter_policy 把 load+delete 包进 BEGIN IMMEDIATE 关掉 peer race（R10）。M-1 持久化侧 — 新增 4 个 per-surface ars_effective_scalars keys（judge_sample_rate_{cold_start,warm}_{synthesis,concept_summary}），带一次性 legacy fallback 保 downgrade 兼容。M-5 / M-6 rollback 静态阈值 anchoring + outer simplex↔legacy 按 runtime_adoption_weight 混合。加上 L1 sanitize_bootstrap_priors cap、L4 auth-policy 回归锁、L5 doctor recovery、L7 release-gate 测试覆盖。1462 测试 / 0 失败 / 3 ignored / 0 clippy / 0 fmt。Default-OFF 行为与 v0.28.7 二进制一致。License: AGPL-3.0-or-later。详见下方最近版本。

完整英文 manual 见 docs/manual/README.md，引用表和命令/API 速查见 docs/reference/。

核心特性

安装

从源码安装

git clone https://github.com/lyr1cs/rein.git
cd rein

# 标准构建（CLI + MCP 服务）
cargo install --path crates/rein --locked

# 完整构建（包含 Neural Wiki GUI，推荐）
cd crates/rein/gui && npm ci && npm run build && cd ../../..
cargo install --path crates/rein --locked --features gui

或使用安装脚本：

./scripts/install.sh

前置条件

• Rust 工具链 (1.75+)
• Gemini API 密钥（免费额度：1500 请求/天）

GUI 服务管理

# 后台启动 GUI 服务（监听 :8680）
rein gui on

# 停止 GUI 服务
rein gui off

# 或前台运行 MCP + GUI
rein serve --gui

# 在浏览器打开
open http://localhost:8680

快速开始

# 1. 设置 API 密钥
export GEMINI_API_KEY="your-key-here"

# 2. 自动配置所有检测到的 MCP 客户端
rein init

# 3. 启动 MCP 服务（通常由客户端自动启动）
rein serve

CLI 命令参考

Cleanup 工作原理（保留溯源）

rein 的清理管线是保留溯源的：永远不会硬删除信息。流程分三个阶段：

1. 合并（Consolidation） — 将 topic 变体（如 Docker Deployment / docker-deployment）归组，每组内所有记忆合并为一条高质量 canonical 记忆。原始记忆作为 evidence 保存到 memory_evidence 表，保留原始内容、时间戳和关键词。

2. 去重（Dedup） — 在每个 topic 组内扫描内容级重复，使用词汇相似度（Jaccard + containment）和可选的嵌入余弦相似度。匹配的"输家"的独特内容被附加到"赢家"上（带溯源标记 [merged from <id> on <date>]），然后作为 evidence 记录。

3. 自适应刷新 — 合并和去重完成后，自适应引擎（M1-M6）运行：HDBSCAN 重聚类、生存曲线重建、层级边界更新、alpha/阈值学习处理新事件。

每次合并决策都记录在 dedup_decisions append-only 账本中，包含赢家/输家 ID、分数、关系类型、置信度和操作者。这是 rein 的 reflog — 你可以随时追溯一条 canonical 记忆是如何形成的。

# 预览清理效果（安全）
rein cleanup --all --dry-run

# 对特定 topic 清理
rein cleanup "docker-deployment"

# 全库清理
rein cleanup --all

# 通过 worker 入口执行清理
rein worker cleanup --all

consolidate 兼容旧用法 rein consolidate <topic> -s "summary"，同时新增：

• --topics a,b,c：按显式 topic 列表批量处理
• --pattern 'rmcp*'：按 glob 批量匹配
• --all：处理所有 topic
• --merge-variants：先把大小写、空格、连字符、下划线等 topic 变体归并后再合并
• 不传 --summary：由 rein 自动生成 consolidated memory；有可用 LLM 时优先用 LLM，没有则回退到本地规则

批量 consolidate 会异步并行生成各 group 的 LLM summary/content，但 SQLite 写入仍按顺序事务提交。清理完成后还会写入 adaptive feedback，并刷新一轮 M1-M6 状态。

如果你想完全在 terminal 里自己跑全库清理：

• destructive 全库清理使用 rein cleanup --all
• rein cleanup --dry-run 先预览
• 后台式清理由 rein worker cleanup ...、rein worker cleanup-queue 和 cleanup queue worker 承担

store 热路径里的灰区 dedup 现在也会走专门异步队列：

• 新记忆先正常入库，不阻塞等待远程 LLM
• 后台 dedup-queue worker 再对灰区 pair 做结构化判定
• 需要手动消费时可运行 rein worker dedup-queue

可观测性命令：

• rein canonicals 查看 canonical memory 及其 support / merge 计数
• rein evidence <canonical_id> 查看被吸收的 evidence 快照
• rein dedup-log 查看最近的 dedup ledger

MCP 工具

以 MCP 服务运行时（rein serve），Rein 通过 operation inventory 暴露 40 个 production MCP 工具。权威清单维护在 docs/reference/mcp-tools.md，分为：

• 核心记忆：store、recall、update、forget、recent、topics、canonicals、evidence、stats、health。
• 维护：GC、dedup、concept dedup、organize、consolidate、cleanup、resummerize、archive summary refresh。
• 知识图谱与时序：memoir 工具、concept state、concept summary refresh、timeline、concept history。
• 自适应、会话、ARS 与 judge：feedback、adaptive status、session ingest、synthesis judge、concept-summary judge。

知识图谱关系类型

part_of, depends_on, related_to, contradicts, refines, alternative_to, caused_by, instance_of, superseded_by

LLM 提取层 (v0.3)

rein 使用 LLM（Gemini 3.1 Flash Lite 或本地模型）进行结构化记忆提取，自动构建知识图谱。

架构：

• hook_post — 本地模式提取（崩溃安全网）+ 缓冲到 session 文件
• hook_compact — 记录 compact 上下文，交给异步 memory worker 提炼
• hook_stop — 完整知识提取：记忆 + 概念 + 关系 + 会话摘要（异步 worker）
• hook_session_start / hook_prompt — 可选使用 Codex additionalContext 注入 Rein working surface
• hook_pre_tool_use / hook_permission_request — deny-only Codex guardrail，用于拦截明显危险的 shell 命令

升级旧记忆：

rein upgrade --dry-run    # 预览
rein upgrade              # 将旧记忆转为知识图谱

配置：

[extract]
provider = "google"    # 或 "omlx" 或 "none"

[extract.google]
model = "gemini-3.1-flash-lite-preview"
max_input_chars = 0    # 0 = 不截断（1M token 模型）

[extract.omlx]
endpoint = "http://localhost:11434/v1"  # Ollama, LM Studio, vLLM 等
model = "default"
max_input_chars = 16000

自学习质量系统 (v0.3.0)

rein 自动学习哪些记忆有用、哪些是噪声，无需人工调参。

工作原理：

1. LLM 在提取时给出 quality_confidence (0-1) — 零额外 API 成本
2. 系统追踪 recall → access 模式，分类"好记忆"（被使用）和"差记忆"（被召回但未使用）
3. 特征权重自动从数据学习：使用率、新颖度、连通度、时效性
4. 自适应入口阈值：近期质量低 → 收紧，高 → 放松
5. GC 清理质量低且被召回 5+ 次但从未使用的概念

无需手动调参 — 冷启动用 LLM 判断，数据逐渐接管。

基于：ICLR 2026 Admission Control, PropMem (Prosus), FActScore, MACLA。

配置

rein 按以下优先级加载配置（高优先级覆盖低优先级）：

1. 环境变量
2. TOML 配置文件（$REIN_CONFIG 或 ~/.config/rein/config.toml）
3. 编译时默认值

环境变量

config.toml

[database]
path = "auto"                          # "auto" = ~/.rein/memories.db

[embedding]
provider = "google"    # 或 "omlx" 或 "none"
dimensions = 3072

[embedding.google]
model = "gemini-embedding-001"

[embedding.omlx]
endpoint = "http://localhost:8000/v1"
model = "default"

[search]
rrf_k = 60.0
rrf_fts_weight = 0.3
rrf_vec_weight = 0.7

dedup_similarity = 0.70    # 使用 max(jaccard, containment) 相似度
dedup_time_window_days = 7

[chunking]
max_tokens = 512
overlap_percent = 10
metadata_prefix = true

[sync]
supermemory_enabled = true
auto_memory_enabled = true
auto_memory_glob = "~/.claude/projects/*/memory/**/*.md"

[decay]
base_lambda = 0.06
ltm_beta = 0.8
stm_beta = 1.2
interval_hours = 24
prune_threshold = 0.05
stm_to_ltm_access_count = 5

[server]
compact = false
sse_enabled = false
sse_port = 8680
sse_bind = "127.0.0.1"

数据库

数据库默认存储在 ~/.rein/memories.db。rein 会自动从旧位置迁移数据。

可通过 REIN_DB 环境变量或 [database] path 配置项覆盖路径。

Claude Code Hook 设置

在 Claude Code 的 settings.json 中添加以下内容以启用自动记忆提取：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "rein hook post", "timeout": 10 }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "rein hook compact", "timeout": 10 }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "rein hook stop", "timeout": 30 }
        ]
      }
    ]
  }
}

Hook 行为说明：

• PostToolUse -- 本地模式提取（崩溃安全网）+ 缓冲到 session 文件
• PreCompact -- 记录重要上下文并交给异步 memory worker
• Stop -- 完整知识提取：记忆 + 概念 + 关系 + 会话摘要（通过异步 worker）

Codex CLI Hook 设置

Codex CLI 需要启用 codex_hooks = true，并在 ~/.codex/hooks.json 或
~/.codex/config.toml 的 [hooks] 表中声明 hook。rein init 会配置 Codex
MCP entry，并安装以下 hook：

• SessionStart -> REIN_AGENT_LABEL=codex rein hook session-start
• PreToolUse -> REIN_AGENT_LABEL=codex rein hook pre
• PermissionRequest -> REIN_AGENT_LABEL=codex rein hook permission
• PostToolUse -> REIN_AGENT_LABEL=codex rein hook post
• UserPromptSubmit -> REIN_AGENT_LABEL=codex rein hook prompt
• Stop -> REIN_AGENT_LABEL=codex rein hook stop

Codex 的 hook payload 和 Claude Code 不完全相同。Rein 会识别
hook_event_name、tool_input、tool_response、prompt、
last_assistant_message 和 transcript_path。其中 PostToolUse 和 Stop
接入同一套异步记忆管线；PreToolUse 和 PermissionRequest 是 deny-only
guardrail。SessionStart 与 UserPromptSubmit 可在显式启用后输出 Codex
官方 additionalContext JSON：

[hooks.codex]
inject_prompt_context = true
inject_session_context = true
max_additional_context_chars = 4000

通过 HTTP/SSE 远程访问

启动 SSE 传输以支持远程或多客户端访问：

rein serve --sse

默认绑定地址为 127.0.0.1:8680。

若要绑定到非 localhost 地址，必须设置 REIN_HTTP_TOKEN 环境变量以启用 bearer token 认证：

export REIN_HTTP_TOKEN="your-secret-token"

在 config.toml 中配置绑定地址和端口：

[server]
sse_enabled = true
sse_port = 8680
sse_bind = "0.0.0.0"    # 需要设置 REIN_HTTP_TOKEN

透明代理 (v0.10.0)

rein 可以作为透明 HTTP 代理运行，记录 LLM 对话而不修改请求。支持任何允许自定义 base URL 的 agent。

快速开始

# 1. 启动代理（后台运行）
rein serve --proxy &

# 2. 配合你的 agent 使用
ANTHROPIC_BASE_URL=http://127.0.0.1:8690 claude       # Claude Code
codex -c 'model_providers.rein_proxy={ name = "Rein Proxy", base_url = "http://127.0.0.1:8690/v1", env_key = "OPENAI_API_KEY", wire_api = "responses", supports_websockets = false, env_http_headers = { "x-rein-token" = "REIN_PROXY_TOKEN" } }' -c 'model_provider="rein_proxy"'

Shell 别名（推荐）

添加到 ~/.zshrc 或 ~/.bashrc：

alias rein-proxy="rein serve --proxy &"
claudep() { REIN_PROXY_ACTIVE=1 ANTHROPIC_BASE_URL=http://127.0.0.1:8690 ANTHROPIC_CUSTOM_HEADERS="x-rein-token: ${REIN_PROXY_TOKEN:-}" claude "$@"; }
codexp() { REIN_PROXY_ACTIVE=1 codex -c 'model_providers.rein_proxy={ name = "Rein Proxy", base_url = "http://127.0.0.1:8690/v1", env_key = "OPENAI_API_KEY", wire_api = "responses", supports_websockets = false, env_http_headers = { "x-rein-token" = "REIN_PROXY_TOKEN" } }' -c 'model_provider="rein_proxy"' "$@"; }
codexsubp() { REIN_PROXY_ACTIVE=1 codex -c 'model_providers.rein_sub_proxy={ name = "Rein Subscription Proxy", base_url = "http://127.0.0.1:8690", requires_openai_auth = true, wire_api = "responses", supports_websockets = false }' -c 'model_provider="rein_sub_proxy"' -c 'chatgpt_base_url="http://127.0.0.1:8690/backend-api"' "$@"; }
codexsubpws() { REIN_PROXY_ACTIVE=1 codex -c 'model_providers.rein_sub_proxy_ws={ name = "Rein Subscription Proxy WS", base_url = "http://127.0.0.1:8690", requires_openai_auth = true, wire_api = "responses", supports_websockets = true }' -c 'model_provider="rein_sub_proxy_ws"' -c 'chatgpt_base_url="http://127.0.0.1:8690/backend-api"' "$@"; }

然后：rein-proxy 启动代理，claudep、codexp、codexsubp 或 codexsubpws 使用。对于 ChatGPT 登录的 Codex，codexsubp 仍然是推荐的 loopback 入口；回归 smoke 可以直接跑 ./scripts/smoke_codexsubp.sh。如果要验证 websocket-first 路径，可以跑实验性的 ./scripts/smoke_codexsubp_ws.sh。
codexsubp / codexsubpws 的 provider override 实际都由 scripts/codexsubp_provider.toml.tmpl 生成，这个模板是 requires_openai_auth = true 的唯一配置源。

Codex CLI 配置（替代方案）

也可以直接在 ~/.codex/config.toml 中使用自定义 provider 永久配置：

[model_providers.rein_proxy]
name = "Rein Proxy"
base_url = "http://127.0.0.1:8690/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
supports_websockets = false
env_http_headers = { "x-rein-token" = "REIN_PROXY_TOKEN" }

model_provider = "rein_proxy"

这样所有 Codex 调用默认走 rein proxy（需先启动 proxy）。

支持的 Agent

注意： Codex 订阅/OAuth 登录态 proxy 与上面的 API-key Responses API proxy 不是同一个实现。API-key Codex 继续走 codexp；ChatGPT 登录的 Codex 现在仍推荐走 codexsubp。这个入口会保留 requires_openai_auth = true，把 chatgpt_base_url 指向本地 rein proxy，并显式关闭 websocket 传输，让 first-party backend、helper/discovery 路径和 /responses 记录链路保持在 loopback 上。rein 现在也提供实验性的 codexsubpws / smoke_codexsubp_ws.sh，它保留 websocket 传输，并在上游 websocket 不可用时依赖本地 426 Upgrade Required 回退。后续重点是 hardening 与自动化，而不是补齐基础功能。

对于 loopback 场景下的 ChatGPT 登录 Codex，当前最实用的入口是 codexsubp。它使用一个 requires_openai_auth = true 的自定义 provider，这样仍然走 ChatGPT 登录态，但 provider 本身指向本地 rein proxy，并显式关闭 websocket 传输；同时把 chatgpt_base_url 也指向本地 proxy，让模型 API 和 helper/discovery 请求一起走 proxy。这条路径绕开了当前 upstream websocket 403/Cloudflare 问题，同时把订阅登录态固定在本地 record-only 路线上。非 /responses 的 first-party 路径保持 artifact-mirror-only，只做透明转发和原始 artifact 镜像，不做结构化提取。
即便客户端主动发起 websocket upgrade，rein 现在也只会对结构化文本的 /responses 路径升级；其它 first-party 路径会保持普通 HTTP，并继续沿用 artifact-mirror-only 策略。

工作原理

• 代理拦截 /v1/messages（Anthropic）、/v1/chat/completions（OpenAI）、/responses / /v1/responses（Codex / OpenAI Responses API），并透明转发 /backend-api/codex/*（Codex first-party backend），同时把 /wham/*、/connectors/*、/v1/agent/register、/authenticate_app_v2、/codex/safety/arc 等 ChatGPT helper/discovery 路径路由到 ChatGPT backend root
• 请求原样转发（仅记录，不注入）
• 异步从 assistant 响应中提取记忆并存储
• SSE 流式传输逐字节透传，零延迟影响
• 其他端点（如 /v1/models）原样透传

异步记忆管线 (v0.10.0)

记忆提取现在完全异步化。Hook 将任务排入文件队列，后台 worker 使用 LLM 提取、去重和持久化。

# 手动清空队列（通常自动触发）
rein worker memory

架构：

• hook_post / hook_compact / hook_stop 将任务排入 ~/.rein/memory_queue_<project>.jsonl
• 后台 worker 处理任务，支持指数退避和死信队列
• 跨会话去重（指纹 + 内容相似度）
• Working Set — 项目级记忆表面，每次提取时更新
• Always-on Index — 稳定的高质量摘要，用于项目级上下文

Neural Wiki 图形界面 (v0.11.0)

rein 内置 Web 图形界面，用于可视化探索记忆系统。GUI 通过 rust-embed 嵌入二进制文件 — 无需额外 Web 服务器。

快速开始

# 带 GUI 构建
cd crates/rein/gui && npm ci && npm run build && cd ../../..
cargo install --path crates/rein --locked --features gui

# 启动 GUI 服务（自动启用 SSE）
rein serve --gui

# 在浏览器打开
open http://localhost:8680

页面

认证

设置 REIN_HTTP_TOKEN 后，API 端点需要 Bearer 令牌认证。GUI 页面本身无需认证，可以在设置页面输入令牌。

最近版本

v0.21 → v0.28.8 这一段重构围绕三条主线：统一 operation registry、ARS（Adaptive Read-Side Synthesis）反馈驱动闸门栈、以及对每个 adaptive 表面的端到端 audit-cycle 强化。

v0.28.8 维持 v0.28.7 的默认行为：仅 [ars.acceleration] 默认开启（仍 fail-closed：没有健康 ars_parameter_policy canary 与正向 scoped adoption weight 时，learned 参数不影响 runtime）。runtime LLM judge（[ars.llm_judge]）及其 nightly_cron 仍按 v0.28 charter Non-Goal 默认 false——operator 必须显式 opt-in（产生 LLM API 计费）。ARS 内容生成能力（[ars].concept_summary_enabled、recall_synthesis_enabled、cold_archive_enabled）和 [resummerize].enabled 仍由 operator 显式控制。

自适应引擎 (v0.6.0+)

核心理念是通过数据驱动自适应逐步减少固定参数。冷启动和安全边界仍保留 bootstrap 默认值，自适应引擎在慢通道把 fusion、decay、tiering、threshold 行为推向真实反馈。

管线顺序：M4 → A1 → M3 → M5 → M2 → M6

另外：

• 嵌入语义去重 — GC 慢通道，捕捉 Jaccard 遗漏的改写
• 保留溯源的合并 — 时间锚点和独特细节永不丢失
• Snapshot CAS — 自适应状态保存使用 read-merge-write + 版本冲突重试

架构图

记忆存储流程

flowchart TD
    A[输入文本 / 工具输出] --> B[hook_post 或 rein_store]
    B --> C[LLM 提取\nGemini Flash Lite / OMLX]
    C -->|LLM 不可用| D[规则兜底\ntopic · summary · keywords · importance]
    C --> D2[postprocess\n日期检测 · 偏好标注]
    D --> D2
    D2 --> E{store_with_dedup\nBEGIN IMMEDIATE}
    E -->|sim ≥ 聚类阈值 A1| F[保留溯源合并\n输家 → evidence 记录]
    E -->|sim 在灰区| G[LLM 去重裁决\nasync dedup-queue]
    E -->|全新记忆| H[INSERT memories]
    H --> I[auto_link\n双向 related_ids]
    I --> J[evolve\n知识演进]
    J --> K[HNSW + Tantivy 索引更新\nfire-and-forget]
    K --> L[needs_vec_dedup 标记\nGC 慢通道嵌入去重]
    F --> M[dedup_decisions 账本]
    G --> M

召回管线

flowchart TD
    Q[查询] --> CL[查询分类器\n6 种策略 · 规则驱动 · 0 LLM 调用]
    CL -->|策略 + alpha| EX[查询扩写\nGemini / OMLX → 2-3 个变体]
    EX --> P1[通道 1：Tantivy BM25\n本地 · <1ms]
    EX --> P2[通道 2：HNSW 向量\n本地 ~5ms / Gemini API ~255ms]
    EX --> P3[通道 3：KG FTS + BFS\n概念落点扩展]
    P1 --> FU[RRF / CC 融合\n学到的 alpha M2]
    P2 --> FU
    P3 --> FU
    FU --> TF[M5 层级过滤\nCold 记忆在非 Exploratory 查询中排除]
    TF --> SW[强度加权\nper-cluster KM 曲线 M3 → 全局先验 → 艾宾浩斯]
    SW --> RF[多特征重排序\n8 特征 · 学到的权重]
    RF -->|可选| LR[LLM 重排序\nGemini / OMLX · 高置信度绕过]
    RF --> CC[Canonical 优先折叠\nevidence_preview 附加]
    LR --> CC
    CC --> CV[交叉验证\nSupermemory + auto-memory 文件]
    CV --> RES[最终结果\n置信度 95%/85%/62% 按来源数]

压缩（PreCompact Hook）

flowchart TD
    T[PreCompact 触发\n上下文窗口接近上限] --> HC[hook_compact\n记录 compact 上下文]
    HC --> SB[读取 session buffer\n累积的工具输出 + 对话轮次]
    SB --> LE[LLM 提取\n记忆 + 概念 + 关系]
    LE --> WQ[异步记忆队列\n~/.rein/memory_queue_<project>.jsonl]
    WQ --> BW[后台 worker\nrein worker memory]
    BW --> SD[store_with_dedup\nper-memory 去重 + 合并]
    SD --> EP[创建 Episode 节点\n会话 → concept_ids + memory_ids]
    EP --> TL[更新 ConceptLink 时间窗口\nvalid_from / valid_until]
    TL --> CL[清空 session buffer\n准备好迎接下一个上下文窗口]

    style T fill:#f96,color:#000
    style EP fill:#6af,color:#000

架构

flowchart TD
    U[用户 / AI 智能体]
    CLI[CLI\n20+ 命令]
    MCP[MCP 服务\n38 工具 · stdio / HTTP / SSE]
    GUI[Neural Wiki GUI\nReact + Tailwind]
    PXY[代理\nClaude · Codex 订阅 · record-only]

    U --> CLI
    U --> MCP
    U --> GUI
    U --> PXY

    CORE[rein core]
    CLI --> CORE
    MCP --> CORE
    GUI -->|inventory-backed REST API| CORE
    PXY -.->|异步队列| CORE

    REC[召回管线\n三通道 + RRF/CC + 重排 + canonical 优先]
    ST[存储 · 去重 · 演进\n自动关联 · 保留溯源合并]
    HK[Hooks\npost · compact · stop]
    ADP[自适应引擎\nM1-M6 + A1]
    KG[知识图谱\nmemoir · concept · episode · 时序链接]

    CORE --> REC
    CORE --> ST
    CORE --> HK
    CORE --> ADP
    CORE --> KG

    DB[(SQLite memories.db\nmemories · FTS5 · sqlite-vec)]
    TN[Tantivy BM25 旁路索引]
    US[usearch HNSW 旁路索引]

    REC --> DB
    ST --> DB
    HK --> ST
    ADP --> DB
    KG --> DB

    ST -.fire-and-forget.-> TN
    ST -.fire-and-forget.-> US
    REC -.reads.-> TN
    REC -.reads.-> US

    style DB fill:#6af,color:#000
    style CORE fill:#f96,color:#000

存储是唯一真实来源（memories.db）：SQLite + FTS5 + sqlite-vec。Tantivy 和 usearch 是派生的旁路索引，由召回管线查询，存储写入 fire-and-forget 更新它们，不阻塞热路径。

搜索管线

1. Tantivy BM25 -- Tantivy 全文搜索（回退到 FTS5），亚毫秒级
2. HNSW ANN -- O(log n) 近似最近邻（usearch），回退到 sqlite-vec 暴力搜索
3. 缓存向量 -- sqlite-vec 中预计算的嵌入向量
4. API 向量 -- 通过 gemini-embedding-001（或 OMLX 本地后端）按需嵌入
5. RRF 融合 -- 加权倒数排名融合合并所有结果列表
6. 艾宾浩斯评分 -- strength(t) = exp(-lambda_eff * days^beta) 加权最终排序

嵌入后端

rein 使用 EmbedderKind 枚举分发支持多种嵌入后端：

• Google（gemini-embedding-001）-- 默认，3072 维；provider benchmark 细节见 docs/reference/bibliography.md
• OMLX -- 通过 OpenAI 兼容 API 端点进行本地嵌入

在配置中设置 [embedding] provider 为 "google"、"omlx" 或 "none"。

代理 / Endpoint 覆盖

国内用户或防火墙环境，所有 API 端点均可配置：

直接代理（Cloudflare Worker、Nginx 反代）：

[embedding.google]
endpoint = "https://your-gemini-proxy.com"
# 请求路径: {endpoint}/v1beta/models/gemini-embedding-001:embedContent

[sync]
endpoint = "https://your-supermemory-proxy.com"

OpenRouter 等 OpenAI 兼容聚合商：

[embedding]
provider = "omlx"

[embedding.omlx]
endpoint = "https://openrouter.ai/api/v1"
model = "google/gemini-embedding-001"

OMLX 后端使用 OpenAI /v1/embeddings 格式，兼容 OpenRouter、LiteLLM 等服务。

记忆衰减模型

• Critical 记忆永不衰减（强度始终为 1.0）
• STM（短期记忆）：衰减较快（beta = 1.2），通过聚类生存曲线驱动晋升为 LTM（回退：5 次访问）
• LTM（长期记忆）：衰减较慢（beta = 0.8），分配给 high / critical 重要度
• 访问次数减缓衰减：lambda_eff = lambda / (1 + access_count * 0.2)

支持的客户端

rein init 自动检测并配置：

• Claude Code
• Claude Desktop
• Cursor
• Windsurf
• VS Code (Copilot)
• Gemini CLI
• Codex
• OpenCode

性能目标

成本估算

许可证

Copyright (C) 2026 Eric Lee. 保留所有权利，除非依 AGPL-3.0-or-later 授权。

AGPL-3.0-or-later — 见 LICENSE。

rein 是一个 server（MCP / REST / GUI）。AGPL §13 网络使用条款要求：如果你改造 rein 后以网络服务形式提供给用户（SaaS / 公开 endpoint），必须把修改后的源代码让那些用户能拿到。自托管个人使用、组织内部部署、以及通过 API 调用 rein 的集成（Claude Code / Cursor / IDE 插件等）都不受影响。

如果需要非 AGPL 的 license 用于商业 / 闭源场景，本项目 copyright holder（Eric Lee）保留 dual-license 权利——开 issue 联系。