Metadata-Version: 2.4
Name: cortistrate
Version: 0.1.0
Summary: Cortistrate — markdown memory framework for AI agent swarms; cross-machine, multi-agent, self-hosted
Project-URL: Homepage, https://cortistrate.dev
Project-URL: Repository, https://github.com/mark1kwok/cortistrate
Project-URL: Changelog, https://github.com/mark1kwok/cortistrate/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/mark1kwok/cortistrate/issues
Author: Cortistrate AI
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agent,cortistrate,markdown,memory,pgvector,postgresql,rag
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: anyio>=4.0
Requires-Dist: apscheduler<4.0,>=3.10.4
Requires-Dist: asgiref>=3.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: greenlet>=3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jieba<1.0,>=0.42.1
Requires-Dist: numpy>=1.26
Requires-Dist: openai>=1.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: portalocker>=2.8.2
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: psycopg-pool<4,>=3.2
Requires-Dist: psycopg[binary]<4,>=3.1
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.7.1
Requires-Dist: python-multipart>=0.0.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: structlog>=24.0.0
Requires-Dist: textual>=8.2.7
Requires-Dist: tiktoken>=0.7
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: watchfiles>=0.21.0
Provides-Extra: multimodal
Requires-Dist: cairosvg>=2.7.0; extra == 'multimodal'
Description-Content-Type: text/markdown

<div align="center">

# 🧠 Cortistrate

**The Agent Swarm Memory Cortex (大脑皮层)**

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

[Quick Start](#quick-start) · [Install](#install) · [Research & Philosophy](docs/research/agent_memory_philosophy.md) · [Docs](docs/) · [Integrations](#integrations)

</div>

---

## 🌟 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](docs/research/agent_memory_philosophy.md)**).

```
┌─────────────────────────────────────────────────────────────────────────┐
|                          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](docs/research/agent_memory_philosophy.md)**

---

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

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

*Or via PyPI:*

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

### 2. Write & Search Memories

```bash
# 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](https://arxiv.org/abs/2402.17753)), 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](benchmarks/README.md) to reproduce the LoCoMo benchmark locally.

---

## 🧩 Integrations

### Hermes Agent
```bash
hermes plugins install cortistrate
```
See [integrations/hermes/](integrations/hermes/) for full configuration and tools.

### Claude Code
```bash
claude plugin marketplace add cortistrate/cortistrate-claude-code
claude plugin install cortistrate
```
See [integrations/claude-code/](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](docs/architecture.md) for the complete architecture blueprint.

---

## 📚 Documentation

- 📖 **[Research & Philosophy Paper](docs/research/agent_memory_philosophy.md)** — Architectural philosophy, Cortex paradigm, and theory.
- 📐 **[Architecture Overview](docs/architecture.md)** — Layered DDD design, dependencies, and index pipeline.
- ⚡ **[How Memory Works](docs/how-memory-works.md)** — Step-by-step memory extraction, storage, and retrieval.
- ⚙️ **[Configuration Guide](docs/configuration.md)** — TOML & environment variable settings.
- 🔌 **[API Reference](docs/api.md)** — Complete OpenAPI endpoint specifications.

---

## 🛠 Development

```bash
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](docs/engineering.md) for build and CI conventions.

---

## 🔧 What changed from EverOS

Cortistrate is a fork of [EverOS](https://github.com/EverMind-AI/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](https://github.com/EverMind-AI/EverAlgo)
(boundary detection, memory extraction, ranking, clustering) is vendored under
`src/everalgo/` under the MIT License.

See [ACKNOWLEDGMENTS.md](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](LICENSE).
