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.30.0 (2026-05-10) — built-in OAuth provider for Claude Cowork / claude.ai / mobile remote MCP connectors. Adds explicit [server].auth policy (loopback_only, bearer_required, oauth, public), OAuth Authorization Server metadata, Dynamic Client Registration, authorization code + PKCE S256, refresh rotation, revocation, SQLite-backed clients/grants/signing keys, owner-approval GUI, Connectors management UI, OAuth rein doctor checks, and live-readiness/e2e scripts. The release was validated end-to-end with claude.ai/Cowork over a Cloudflare Quick Tunnel. See the v0.30.0 release.

Previous release: v0.28.18 (2026-05-09) — follow-up audit hardening for the Cowork/auth diagnostics arc. Public unauthenticated HTTP now blocks mutating MCP/REST calls from non-loopback Hosts, while keeping read-only Cowork recall usable; rein doctor now checks both Codex MCP tables, catches non-stdio rein serve --sse/--gui/--proxy entries, flags REIN_DB / REIN_CONFIG / HOME database-split risks, and verifies DXT / Claude plugin manifest versions match Cargo before release.

Previous release: v0.28.17 (2026-05-09) — Cowork/auth diagnostics patch. Runtime auth semantics stayed unchanged, but the two silent traps from the May 9 Cowork incident now surface explicitly: rein serve --gui logs a WARN when REIN_HTTP_TOKEN is set while [server].allow_unauthenticated_loopback=true because token auth wins and the loopback flag is a runtime no-op; rein doctor reports the same http_auth WARN and also checks Codex's ~/.codex/config.toml Rein MCP entry, warning when it points at a non-loopback HTTP URL whose database may differ from the local rein CLI.

Previous release: v0.28.16 (2026-05-09) — Codex 0.129 [mcp.<name>] → [mcp_servers.<name>] compatibility. rein init now writes the new Codex MCP table while preserving and cloning legacy customizations, closing the second half of the Codex 0.129 rename window opened by v0.28.15.

Previous release: v0.28.11 (2026-05-06) — docs-only polish on v0.28.10 adding a Verified end-to-end walkthrough to the Tailscale Funnel recipe in docs/manual/02b-remote-mcp-deployment.md. The walkthrough is the exact 7-step sequence (FQDN discovery via tailscale status --json, ~/.rein/config.toml [server].allowed_hosts entry, env -u REIN_HTTP_TOKEN to defeat shell-inherited bearer auth, tailscale funnel --bg --https=443, Let's Encrypt cert provisioning wait, tail -F /tmp/rein-sse.log as ground truth during connector add, Cowork verification) that successfully brought up a working Cowork connector during v0.28.11 development. Plus a "Common pitfalls" subsection covering the 4 traps an operator can hit: REIN_HTTP_TOKEN env-var inheritance, the plugin-marketplace-vs-custom-connector distinction (both can/should coexist), LAN-side *.ts.net interception, and cert provisioning delay. Companion .gitignore patch (*.crt / *.key / *.pem / *.p12 / *.pfx) blocks accidental commit of TLS material — none was leaked, but tailscale cert writes private keys into cwd and the patch closes that footgun. No runtime / binary changes. Tests / clippy / fmt unchanged from v0.28.10 (1462 / 0 / 3 ignored / 0 / 0).

Previous release: v0.28.10 (2026-05-06) — docs-only patch on v0.28.9 closing the remote-MCP gap for Claude Cowork / claude.ai / mobile. New chapter at docs/manual/02b-remote-mcp-deployment.md — four deployment recipes (Cloudflare Tunnel recommended, Tailscale Funnel, Caddy/nginx + Let's Encrypt, ngrok dev), the exact UI configuration flow for Customize → Connectors → "+" → Add custom connector with OAuth tradeoffs, and an Anthropic-quoted explanation of why the local-stdio paths (DXT / plugin marketplace / claude_desktop_config.json) don't reach Cowork.

Previous 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/. Maintainer guide at docs/guides/dxt-build.md; ADR at docs/decisions/distribution-channels.md. Binary bit-identical to v0.28.8.

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.30.0.mcpb from the v0.30.0 release.

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

   xattr -d com.apple.quarantine ~/Downloads/rein-v0.30.0.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:

# Latest master
cargo install --git https://github.com/lyr1cs/rein --locked rein

# Or pin to a specific release tag (recommended for reproducible installs)
cargo install --git https://github.com/lyr1cs/rein --tag v0.30.0 --locked rein

--locked is required. Without it, cargo install --git ignores the committed Cargo.lock and re-resolves every transitive dependency to the latest semver-compatible version on crates.io, which can pull in C/SIMD code that requires a newer host toolchain than your machine ships. See docs/manual/02-installation.md → Remote Install.

This installs the default non-GUI binary. For the built-in OAuth remote-connector flow, use the GUI-enabled source install in Recipe E so the owner approval pages are embedded.

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

Install via Remote MCP (Cowork, claude.ai, mobile)

Claude Cowork (the agentic-work tab inside Claude Desktop), claude.ai web, and the Claude mobile apps route MCP traffic through Anthropic's cloud, not through your local stdio. They cannot use the DXT or plugin marketplace paths above. They need a public HTTPS endpoint that Anthropic's servers can reach.

rein already implements the Streamable HTTP transport (current MCP standard) at /mcp on its built-in HTTP server. Three prerequisites before exposing it:

1. Set [server].allow_unauthenticated_loopback = true in ~/.rein/config.toml (loopback-only bind, opt-in unauth) OR set REIN_HTTP_TOKEN to a strong secret and have your reverse proxy inject Authorization: Bearer … upstream.

2. Add the public hostname to [server].allowed_hosts in ~/.rein/config.toml, e.g., allowed_hosts = ["rein.your-domain.com"]. Without this, rein returns 403 Host header is not allowed for any request whose Host: is not localhost / 127.0.0.1 / ::1, and your tunnel will appear broken even when up.

3. Start the listener:

   rein serve --sse        # listens on 127.0.0.1:8680/mcp
   

Without one of the auth postures in step 1, rein serve --sse exits immediately with REIN_HTTP_TOKEN must be set. Without step 2 the listener starts but rejects every tunnel request.

Expose the listener publicly via one of (no Tailscale or domain required for the simpler ones):

• Cloudflare Quick Tunnel — cloudflared tunnel --url http://localhost:8680. No account, no domain. Random *.trycloudflare.com URL, ephemeral. Lowest friction; works on most networks (use --protocol http2 if your network blocks QUIC).
• ngrok — free account, no domain. URL ephemeral on free tier; reserved domains on paid. Tends to work on networks where Quick Tunnel can't.
• Tailscale Funnel — free account, no domain. Permanent *.ts.net URL. Most network-tolerant of the no-domain options.
• Cloudflare Tunnel + own domain — permanent URL under your domain, optional Cloudflare Access OIDC for real edge auth.
• Caddy / nginx + Let's Encrypt — self-hosted on your own VPS.

Then in Claude: Customize → Connectors → "+" → Add custom connector, paste your URL (e.g., https://rein.your-domain.com/mcp), optionally add OAuth credentials.

Step-by-step recipes for each tunnel option, the Claude UI configuration flow, and authentication tradeoffs are in docs/manual/02b-remote-mcp-deployment.md.

Note: custom remote connectors require a Pro / Max / Team / Enterprise Claude account. Free-plan users can use the local-stdio paths (DXT, plugin marketplace) but not Cowork.

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.30.0 arc rebuilt rein around three axes: a unified operation registry, an adaptive read-side synthesis (ARS) stack with feedback-driven gates, and secure remote MCP deployment for Claude clients.

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 hooks = true (Codex 0.129+) 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]
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.

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

# 后台启动 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

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

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

# 全库清理
rein cleanup --all

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

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

[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"

{
  "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 }
        ]
      }
    ]
  }
}

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

rein serve --sse

export REIN_HTTP_TOKEN="your-secret-token"

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

# 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"'

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"' "$@"; }

[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"

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

# 带 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

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% 按来源数]

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

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

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

[embedding]
provider = "omlx"

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