cortistrate 0.1.0

Cortistrate — markdown memory framework for AI agent swarms; cross-machine, multi-agent, self-hosted

🧠 Cortistrate

The Agent Swarm Memory Cortex (大脑皮层)

Markdown Source of Truth · Sub-second Cascade Sync · Postgres Vector Search · Multi-Agent Adaptive

Quick Start · Install · Research & Philosophy · Docs · Integrations

---

🌟 What is Cortistrate?

Cortistrate is a Python framework and runtime memory engine that gives AI coding assistants, chat applications, and autonomous agents a portable, persistent, and self-evolving memory layer. Built for Agent Swarm readiness — multiple agents across multiple machines share one memory server.

While current LLMs provide powerful raw reasoning, their APIs are inherently stateless. Agent frameworks supply the execution loops and tool bindings ("hands and feet"), but without a long-term memory layer, agents remain transient execution scripts.

Cortistrate acts as the Cortex (大脑皮层) for AI Agents — storing conversations, user preferences, codebase knowledge, and execution trajectories as plain Markdown on disk, and syncing them into high-performance vector/keyword indexes for instant context retrieval.

---

🔬 Top-Level Philosophy & Research

Cortistrate is grounded in deep research on cognitive architectures, memory models, and agentic workflows (published in our Research & Philosophy Paper).

┌─────────────────────────────────────────────────────────────────────────┐
|                          AI AGENT COGNITIVE ARCHITECTURE                 |
├─────────────────────────────────────────────────────────────────────────┤
| 1. LLM Backend (API)     --> Brainstem / Basal Ganglia (Stateless Core) |
| 2. Agent Framework       --> Sensorimotor Exoskeleton (Hands & Feet)   |
| 3. Cortistrate Substrate --> Agent Cortex (大脑皮层 - Persistent State)    |
└─────────────────────────────────────────────────────────────────────────┘

Key Research Insights:

1. Sensorimotor Exoskeleton + Cortex: Backend LLMs handle raw computation; client-side agent loops form the Sensorimotor Exoskeleton (感觉运动外骨骼). Cortistrate provides the Cortex (大脑皮层), turning stateless models into persistent AGI assistants.
2. State-Weight Decoupling: Managed cloud agents and managed APIs (CoT, Code Interpreters) cannot replace local memory layers. Trillion-parameter static model weights cannot be mutated for local company codebases or specific user projects. Agent runtime state must be decoupled from static weights.
3. Isomorphism of Memory & Knowledge: Traditional, rigid Knowledge Graphs (Wikipedia, WordNet) are high-maintenance and brittle. Cortistrate leverages Semantic Vector Space + Hybrid BM25 Retrieval, capturing deep implicit context and solving the LLM's epistemic blindness ("doesn't know what it doesn't know").

📖 Read the Full Research Paper & Reference Philosophy

---

⚡ Key Features

• 📄 Markdown Source of Truth — Human-readable, diffable, and Git-versioned .md files on disk (~/.cortistrate/). Delete all databases, and indexes rebuild 100% from Markdown.
• ⏱️ Sub-Second Cascade Watcher — Edit .md files directly in VS Code, Obsidian, or Neovim; the background watcher automatically syncs SQLite state and Postgres vector indexes.
• 🧬 Dual-Track & 5-Axis Namespace — Explicit separation between User Track (episodes, user profile) and Agent Track (trajectories, skills), isolated across user_id, agent_id, app_id, project_id, and session_id.
• 🔄 Self-Evolving Offline Memory Engine (OME) — Background reflection cycles consolidate raw conversation episodes into atomic facts, dynamic user profiles, and reusable workflow skills.
• 🔍 Hybrid Postgres / PGLite Vector Search — Combines pgvector semantic similarity with BM25 keyword matching and scalar filtering.
• 🔌 Seamless Agent Integrations — Ready-to-use plugins for Hermes Agent, Claude Code, FastAPI HTTP API, and a full-featured CLI.

---

🚀 Quick Start

1. Installation

# One-liner automated setup (checks Python >= 3.12, installs cortistrate, runs init)
curl -fsSL https://cortistrate.dev/install.sh | bash

Or via PyPI:

pip install cortistrate
cortistrate init
cortistrate server start   # Starts HTTP API server on http://127.0.0.1:8000

2. Write & Search Memories

# Memorize a user preference
cortistrate memorize \
  --user-id me \
  --text "I prefer dark mode, strict Python typing, and concise responses"

# Perform hybrid semantic search
cortistrate search --user-id me --query "developer UI preferences"

---

📊 Benchmark Performance

Cortistrate includes a self-contained runner for the LoCoMo (Long Conversation Memory) benchmark (Maharana et al., 2024), evaluating multi-session retrieval across single-hop, multi-hop, open-domain, and temporal questions:

Category	Description	Cortistrate Accuracy
Single-hop	Direct fact retrieval from single session	94.0%
Multi-hop	Cross-session reasoning and synthesis	91.0%
Open-domain	General knowledge grounded in dialogue	80.2%
Temporal	Time-sensitive questions & date reasoning	95.5%
Overall Majority	1,540 multi-session QA evaluations	93.3%

See benchmarks/README.md to reproduce the LoCoMo benchmark locally.

---

🧩 Integrations

Hermes Agent

hermes plugins install cortistrate

See integrations/hermes/ for full configuration and tools.

Claude Code

claude plugin marketplace add cortistrate/cortistrate-claude-code
claude plugin install cortistrate

See integrations/claude-code/ for details.

HTTP API Endpoints

Cortistrate exposes a FastAPI server (http://localhost:8000):

• POST /api/v1/memory/flush — Extract & store memories from conversation sessions.
• GET /api/v1/memory/search — Hybrid vector + BM25 memory retrieval.
• GET /api/v1/memory/profile — Fetch structured user profile.
• POST /api/v1/memory/reflect — Trigger background memory consolidation.

Interactive OpenAPI docs available at http://127.0.0.1:8000/docs.

---

🏗 Architecture

┌──────────────────────────────────────────────────────────────────┐
│                   Markdown Truth Files (`.md`)                   │
│          `~/.cortistrate/{users, agents, knowledge}/*.md`         │
└──────────────────────────────────────────────────────────────────┘
                               │
                       [Cascade Watcher]
                               │
            ┌──────────────────┴──────────────────┐
            ▼                                     ▼
┌───────────────────────┐             ┌───────────────────────┐
│     SQLite State      │             │ Postgres / PGLite     │
│  (system.db metadata) │             │ (pgvector + BM25)     │
└───────────────────────┘             └───────────────────────┘

• Markdown Files: Single source of truth. Human-readable, diffable, editable.
• SQLite: Queue state, cascade audit logs, and metadata isolation.
• Postgres / PGLite: Vector ANN search + BM25 full-text + scalar filter in a single query.

See docs/architecture.md for the complete architecture blueprint.

---

📚 Documentation

• 📖 Research & Philosophy Paper — Architectural philosophy, Cortex paradigm, and theory.
• 📐 Architecture Overview — Layered DDD design, dependencies, and index pipeline.
• ⚡ How Memory Works — Step-by-step memory extraction, storage, and retrieval.
• ⚙️ Configuration Guide — TOML & environment variable settings.
• 🔌 API Reference — Complete OpenAPI endpoint specifications.

---

🛠 Development

git clone https://github.com/mark1kwok/cortistrate.git
cd Cortistrate
uv sync          # Install dependencies & set up virtualenv
make ci          # Run linting, unit tests, and integration tests

See docs/engineering.md for build and CI conventions.

---

🔧 What changed from EverOS

Cortistrate is a fork of EverOS by EverMind AI, licensed under Apache-2.0. The core memory pipeline, Markdown-first storage model, and OME reflection engine originate from the EverOS project.

The algorithm library EverAlgo (boundary detection, memory extraction, ranking, clustering) is vendored under src/everalgo/ under the MIT License.

See ACKNOWLEDGMENTS.md for the full list.

Key modifications from the original EverOS:

Production-grade database (LanceDB → PostgreSQL). EverOS shipped with LanceDB — an embedded, research-grade column store that loads entire tables into memory and copies on every mutation, causing memory leaks unsuitable for long-running processes. Cortistrate replaces it with PostgreSQL (or embedded PGLite for single-user setups) backed by pgvector, turning a research prototype into a transactional memory store.

Always-on HTTP server. EverOS was a CLI tool — each invocation loaded, ran, and exited. Cortistrate runs as a persistent HTTP server with a REST API, enabling remote calls from multiple agents simultaneously.

Memory fragment mechanism. The original Episode mechanism loaded one or two full conversation records into context on every turn. Cortistrate's philosophy: remembering the full detail of the last two sessions is pointless — relevance beats recency. We replaced it with a title-based retrieval model that loads 20 concise fact titles into the semantic context, dramatically widening coverage and recall probability without bloating the prompt.

Hermes plugin rewrite. The Hermes provider was rewritten for the Cortistrate server architecture. The original EverOS provider loaded full episode bodies into the system prompt; the rewrite uses title-based memory fragments, keeping the prompt lean while widening coverage.

Claude Code plugin rewrite. The Claude Code plugin was rewritten from the EverMem Cloud plugin (shipped inside the EverOS repo under Apache-2.0). The API client layer, hook scripts, and MCP server target the self-hosted Cortistrate server (no auth, app/project/user scoping) instead of cloud endpoints (Bearer auth, group scoping).

Multi-agent shared memory (Agent Swarm). Multiple agents can share a single Cortistrate instance. In practice this does not cause "personality bleed" — each agent sees the broader context of what others in the swarm are doing, similar to how humans stay informed through communication. Agents that need isolation (e.g. business profiles) can be configured with separate app_id / user_id scopes.

---

📄 License

Apache-2.0 License.