lore (git-lore)

Git-native, encrypted, zero-token-bloat AI context & transcript sync across devices and contributors.

Switch between your desktop and laptop—or hand off a branch to a teammate—and your AI coding agent (Antigravity, Claude Code, Cursor, Codex) immediately knows your past chats, architectural decisions, and debugging context without you ever explaining a thing.

• 0 Cloud Accounts / 0 API Keys: Uses Git itself (refs/ai/lore) as the database and deterministic local compression.

• ~350-Token Always-On Digest + 0-Token Deep Search: Strips 85–95% of raw .jsonl bloat and indexes full transcripts locally via SQLite FTS5 + MCP.

• Private Context on Public Repos: Encrypted with your existing ~/.ssh/id_ed25519 key and https://github.com/<username>.keys via Ed25519 → X25519 ECDH + AES-256-GCM (with automatic API key/token redaction before encryption).

• Zero Git Pollution: Never touches your working tree, never clutters git log, and keeps git status 100% clean.

Quick Start (2 Commands)

# 1. One-time machine setup (registers global MCP server & skill for Antigravity, Claude Code, Cursor)
npx git-lore-cli setup

# 2. Initialize in any Git repository
git lore init

From that moment on, every git push automatically compresses, encrypts, and syncs your repo's AI sessions to refs/ai/lore, and every git pull decrypts and updates the local context rule.

Related MCP server: context-mcp

How lore Compares

Architecture

flowchart LR
    subgraph DeviceA["Desktop (git push)"]
        A1["Local Transcripts\n(Antigravity / Claude / Cursor / Codex)"] -->|"Deterministic Strip\n(85-95% noise removed, 0 API keys)"| A2["Compact Session + Recap"]
        A2 -->|"Gzip + X25519 ECDH\nAES-256-GCM"| A3["Hidden Git Ref\nrefs/ai/lore"]
    end

    A3 <-->|"GitHub Remote\n(Safe on Public Repos)"| B1["Hidden Git Ref\nrefs/ai/lore"]

    subgraph DeviceB["Laptop / Teammate (git pull)"]
        B1 -->|"Decrypt via\n~/.ssh/id_ed25519"| B2["Local Cache\n.git/lore/"]
        B2 -->|"~350 tokens\n(git-excluded)"| B3[".agents/rules/lore-context.md"]
        B2 -->|"0 tokens until queried\n(SQLite FTS5 BM25)"| B4["MCP Server\nlore_search / lore_get_session"]
    end

Private Context on Public Repos (git lore allow)

Because Git allows anyone who clones a public repo to inspect its refs, lore encrypts every session and takeaway using multi-recipient envelope encryption (ssh-ed25519-x25519-aes256gcm):

1. Each payload is compressed with gzip and encrypted with a random 256-bit Content Encryption Key (CEK) via AES-256-GCM.

2. Each authorized contributor's ssh-ed25519 public key is converted to Montgomery X25519 to wrap the CEK via ECDH + HKDF-SHA256.

3. To approve a teammate on a public or private repo, run:

   git lore allow torvalds

   lore automatically fetches their public ssh-ed25519 key(s) from https://github.com/torvalds.keys and re-encrypts refs/ai/lore.

4. To revoke a contributor and rotate encryption keys:

   git lore revoke torvalds

CLI Reference

You can run commands as either lore <cmd> or native Git subcommand git lore <cmd>:

MCP Tools Exposed to Your Agent

Once lore setup is run, your AI agents automatically have access to:

• lore_status — View the repo's Living Digest, recent cross-device sessions, and authorized contributors.

• lore_search — Full-text BM25 search across all past transcripts and takeaways in the repo (0 token cost until searched).

• lore_get_session — Retrieve the verbatim User/Assistant dialogue of any past session by ID or prefix.

• lore_save_takeaway — Record an architectural decision, gotcha, or WIP handoff note into the Living Digest.

• lore_sync — Pull and push encrypted context via refs/ai/lore.

License

MIT