🧠 Cortex

Persistent, long-term memory for AI agents.

Your agent remembers who you are, what you've decided, and what matters to you — across every conversation.

---

Cortex is an OpenClaw plugin that gives any AI agent cognitive memory — the ability to learn about you over time, recall what's relevant, and build a genuine understanding of your preferences, decisions, and commitments.

This isn't RAG over documents. This is an agent that knows you.

Why Cortex?

• Learns, doesn't just retrieve. Every conversation is analyzed. Important facts, preferences, and decisions are automatically extracted and stored. Your agent gets smarter with every interaction.
• Recalls what matters, when it matters. Before every agent turn, Cortex retrieves relevant memories using hybrid search (BM25 + vector similarity + reranking) and injects them into context. No manual prompting required.
• Tracks commitments, not just facts. Cortex doesn't just remember what you said — it tracks what you committed to, flags contradictions in your preferences, and manages open threads you haven't resolved yet.
• Runs in the background. Zero-config by default. Install the plugin, point it at a Cortex server, and your agent has memory. Auto-recall and auto-capture handle the rest.

Quick Start

1. Install

# From GitHub
cd ~/.openclaw/extensions
git clone https://github.com/100yenadmin/evaos-cortex-plugin.git cortex
cd cortex && npm install --omit=dev

2. Configure — add to your openclaw.json:

{
  "plugins": {
    "allow": ["cortex"],
    "load": { "paths": ["~/.openclaw/extensions/cortex"] },
    "slots": { "memory": "cortex" },
    "entries": {
      "cortex": {
        "enabled": true,
        "config": {
          "cortexUrl": "https://your-cortex-server.example.com",
          "apiKey": "your-api-key",
          "ownerId": "my-agent"
        }
      }
    }
  }
}

3. Restart your gateway. Your agent now has persistent memory. Every conversation is captured. Every future turn is enriched with relevant context.

Configuration

Option	Type	Default	Description
cortexUrl	string	http://localhost:8000	Cortex API base URL
apiKey	string	—	API key (optional for local, required for production)
ownerId	string	default	Memory namespace — isolates memories per user/agent
autoRecall	boolean	true	Retrieve relevant memories before each agent turn
autoCapture	boolean	true	Extract and store memories after each agent turn
shadowMode	boolean	false	Dry-run mode — runs extraction but skips storage
retrievalBudget	number	2000	Max token budget for retrieved memories
maxInjectionChars	number	8000	Max characters injected into agent context
retrievalMode	string	fast	Retrieval mode: auto, fast, or thorough

Tools

Cortex exposes 12 tools your agent can call directly:

Tool	Description
cortex_search	Search memories by query — hybrid BM25 + vector retrieval
cortex_remember	Store a new memory (fact, preference, decision)
cortex_forget	Delete a specific memory by ID
cortex_ask	Ask a question answered by searching across all memories
cortex_list_contradictions	Surface conflicting memories for review
cortex_resolve_contradiction	Resolve a flagged contradiction
cortex_add_commitment	Track a new commitment or promise
cortex_update_commitment	Mark a commitment as completed or cancelled
cortex_list_commitments	List active (or all) tracked commitments
cortex_add_open_loop	Track an unresolved thread or topic
cortex_resolve_open_loop	Mark an open loop as resolved
cortex_list_open_loops	List unresolved threads

How It Works

Cortex operates two invisible loops around every agent conversation:

┌─────────────────────────────────────────────────┐
│                  RECALL LOOP                     │
│                                                  │
│  User message → Cortex retrieves relevant        │
│  memories (BM25 + vectors + reranking) →         │
│  Injects into agent context → Agent responds     │
│  with full history awareness                     │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│                  CAPTURE LOOP                    │
│                                                  │
│  Agent responds → Cortex analyzes the            │
│  conversation → Extracts facts, preferences,     │
│  decisions, commitments → Stores as durable      │
│  memories with metadata and embeddings           │
└─────────────────────────────────────────────────┘

Retrieval pipeline:

1. BM25 — fast keyword matching for exact terms and names
2. Vector similarity — semantic search via embeddings for conceptual matches
3. Hybrid fusion — weighted combination of both signals
4. Reranking — final relevance scoring to surface the best memories
5. Budget enforcement — results trimmed to token budget before injection

Memories include metadata (dates, salience, categories) and are deduplicated, contradiction-checked, and relevance-scored at retrieval time.

Benchmarks

🚧 Benchmarks coming soon. We're running evaluations against LoCoMo, AMB, and MSC — the standard long-term memory benchmarks for conversational AI.

Provider	LoCoMo F1	AMB Score	Latency (p50)
Cortex	—	—	—
Mem0	—	—	—
Zep	—	—	—
Letta	—	—	—
MemGPT	—	—	—

Results will be published with full methodology and reproducible evaluation scripts.

Self-Hosting

Cortex is backed by a standalone server you can run anywhere — your own machine, a VPS, or any cloud provider. The server handles memory storage, embedding, retrieval, and lifecycle management.

Self-hosting documentation and the server repository will be available soon. In the meantime, reach out if you'd like early access.

License

MIT — use it however you want.