Why MemCore?

Most AI agent memory frameworks dump raw conversational logs directly into prompts or unverified vector stores. Over time, this creates three fatal failure modes:

1. State Poisoning: When an agent guesses wrong once, that wrong assumption is embedded and re-injected as "truth" in future sessions.
2. Stale Code Drift: Facts about a codebase stay frozen in vector memory long after the underlying source file has been refactored.
3. Cross-Agent Isolation Leaks: Private agent scratchpads bleed into shared project context without access-control boundaries.

MemCore solves this by introducing governed, bitemporal memory with hard SQL-enforced trust boundaries (~/.memcore):

• Two-Zone Isolation: Separates the Raw Ingest Journal (Untrusted) — an append-only ledger of turns and tool calls that is never recalled into prompts — from Governed Canonical Memory (Authoritative).
• Bitemporal Versioning & Tombstone Refusal Guards: Corrections (supersede) create immutable version chains tracking both valid-world time and transaction time. Rejected claims leave a cryptographic Tombstone that blocks identical bad claims from ever being re-admitted.
• Source-File SHA-256 Staleness Detection: Memories bound to a source_file automatically flip their freshness label to stale the instant that file's SHA-256 changes on disk — while unrelated Git commits leave it untouched.
• Sub-Millisecond Hybrid RRF Recall: Fuses SQLite FTS5 BM25 lexical search with in-process sqlite-vec SIMD vector distance and model2vec static embeddings (minishlab/potion-base-8M) via Reciprocal Rank Fusion (RRF, $k=60$) — requiring zero background daemons, zero Docker containers, and zero open network ports.

Visual Before & After: Ungoverned RAG vs. MemCore

Query: "What port does ClickHouse use?"

Recalled Chunks (Unfiltered Cosine Similarity):
1. [0.89] "Let's try connecting to ClickHouse on 8123..."
2. [0.87] "ClickHouse runs on port 9000 in settings.py"
3. [0.85] "We migrated ClickHouse to port 9440 with TLS"

Result:
❌ Contradictory history dumped into prompt
❌ Old port 9000 and failed guess 8123 pollute context
❌ No way to know if settings.py changed since last week

Query: "What port does ClickHouse use?"

Recalled Canonical Memory (Hybrid FTS5 + Vector RRF):
1. [scope=project | lifecycle=accepted
    | verification=source_backed | freshness=current]
   "ClickHouse telemetry analytics migrated to port 9440
    with mTLS (settings.py)"
   └─ supersedes: v1 ("port 9000", valid_until: 2026-10-18)
   └─ tombstone: "port 8123" blocked (rejected)

Result:
✅ Only active canonical truth is returned
✅ Prior version preserved in immutable audit history
✅ SHA-256 of settings.py verified current at read time

Quick Start

1. Universal One-Command Auto-Install (Recommended)

Install memcore, initialize the governed store, and automatically register its stdio MCP server across every supported AI agent CLI and IDE on your machine:

pip install memcore-omnix
memcore init
memcore install

memcore install detects and atomically updates:

• Claude Code (~/.claude.json via official claude mcp add-json) & Claude Desktop (claude_desktop_config.json)
• Google Antigravity & Antigravity IDE (~/.gemini/config/mcp_config.json, ~/.gemini/antigravity/mcp_config.json)
• Gemini CLI (~/.gemini/settings.json) & Codex CLI (~/.codex/config.toml with atomic TOML validation)
• Cursor (~/.cursor/mcp.json), Windsurf, VS Code (Copilot), OpenCode, and Cline

Inspect detected clients or run a full governance & schema diagnostic:

memcore clients
memcore doctor

How Governed Memory Works

flowchart LR
    subgraph Zone1 ["Zone 1: Untrusted Capture"]
        Turns["Raw Agent Turns & Tool Calls"] --> Journal[("ingest_event<br/>Append-Only Journal")]
    end

    subgraph Gate ["Governance & Admission Gate"]
        Journal -->|"Curate / Triage"| Check{"Tombstone &<br/>Fingerprint Check"}
        Direct["Direct memory_remember"] --> Check
    end

    subgraph Zone2 ["Zone 2: Authoritative Canonical Store (~/.memcore)"]
        Check -- "Blocked by Tombstone" --> Reject["Refused (No State Pollution)"]
        Check -- "Admitted" --> Canon[("memory + memory_version<br/>Bitemporal SQLite WAL")]
        Canon --> FTS["FTS5 BM25 Index"]
        Canon --> Vec["sqlite-vec SIMD +<br/>model2vec / FastEmbed"]
    end

    FTS & Vec -->|"Reciprocal Rank Fusion (k=60)<br/>+ SHA-256 Staleness Check"| Recall(["Salience L1 / Full Recall"])

Four-Dimensional Trust Labels

Every recalled memory carries four explicit labels so the consuming agent knows exactly how much authority it holds:

Salience L1 Progressive Recall

When an agent searches memory with include_content=False (or during compact context injection), MemCore generates a 180-character Salience L1 Preview (recall.py) that prioritizes:

1. Hard negations and prohibitions (never, must not, ห้าม)
2. Numerical bounds, ports, timeouts, and version constraints
3. File paths and module identifiers

This cuts memory injection token overhead by up to 80% while keeping critical constraints visible, letting the agent fetch full bodies only for the exact IDs it needs.

Hybrid RRF Recall & Vector Providers

MemCore fuses lexical exactness (SQLite FTS5 BM25 + Unicode substring matching for technical identifiers and spaceless scripts) with dense vector semantics using Reciprocal Rank Fusion ($k=60$).

Configure your embedding provider via --provider or MEMCORE_EMBEDDING_PROVIDER:

Architecture & Modules

Measured Performance & Footprint

Measured on local disk with SQLite WAL, FTS5 BM25, and hybrid RRF retrieval (docs/BENCHMARKS.md):

Python SDK & Operational CLI

Python SDK

from memcore.client import MemCore

with MemCore(project="platform", agent="sora") as mc:
    # 1. Store a governed fact bound to a source file for automatic SHA-256 staleness tracking
    mem_id = mc.remember(
        "ClickHouse telemetry analytics runs on port 9000",
        memory_type="fact",
        source_file="src/settings.py",
    )

    # 2. Hybrid recall (FTS5 BM25 + Dense Vector RRF Fusion)
    hits = mc.search("telemetry database port")
    for hit in hits:
        print(f"[{hit['scope']} | {hit['verification']} | {hit['freshness']}] {hit['content']}")

    # 3. Bitemporal update (preserves immutable prior version history)
    mc.supersede(
        mem_id,
        "ClickHouse telemetry analytics migrated to port 9440 with mTLS",
        reason="security hardening",
    )

MCP Tools Exposed (memcore.mcp_server)

# Database health, WAL integrity, governance invariants, and backup readiness
memcore doctor

# Store and search memories directly from the terminal
memcore remember "Python 3.10+ required for core services" --project platform --agent sora
memcore search "python version" --project platform --agent sora

# Backfill or refresh local embeddings
memcore embed --provider local --all

# Create, verify, and restore atomic database snapshots
memcore backup
memcore backup-status
memcore restore-from-snapshot --snapshot <snapshot-name> --confirm

# Review raw journal events and apply governed triage decisions
memcore journal-stats
memcore journal-review-list --project platform --agent sora
memcore journal-review-decide <event-id> --verdict remember --content "Verified fact" --agent sora

# Export governed project memory into deterministic, SHA-256-signed workspace instruction files
memcore export                      # Writes workspace AGENTS.md
memcore export --host claude-code   # Writes CLAUDE.md
memcore export --host gemini-cli    # Writes GEMINI.md
memcore export --host copilot       # Writes .github/copilot-instructions.md

Multi-Agent Ecosystem Support

Antigravity	Codex	Claude Code	Cursor
DeepSeek Harness	Hermes	OpenCode	Gemini CLI

Recommended Ecosystem Combo

While MemCore operates standalone as your governed memory engine, pairing it with trimtok and Skill Proof completes the Global Agent Trinity — uniting every AI coding client on your machine around three shared local hubs:

flowchart LR
    Task(["Developer Request"]) --> SP["Skill Proof<br/>~/.skill-proof/skills<br/>(Deterministic Skill Router)"]
    SP --> MC["MemCore<br/>~/.memcore<br/>(Governed Bitemporal Memory)"]
    MC --> Agent["Any AI Coding Agent"]
    Agent --> TT["trimtok<br/>~/.trimtok<br/>(88.3% Context Compression + CCR #c1)"]
    TT --> Agent

# Install & link the complete Global Agent Trinity across all your IDEs and CLIs
pip install memcore-omnix trimtok skill-proof
memcore init && memcore install && trimtok install && skill-proof install
skill-proof vault migrate

Verification & License

# Run the complete 605-test governance, bitemporal, concurrency, and hybrid recall harness
python -m unittest discover -s harness -p "test_*.py"

Distributed under the MIT License. Designed and maintained by P Choke & SORA.