corti

🧠 Corti

Cognitive Substrate for AI Agent Swarms

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

[Quick Start](#-quick-start) · [Install & Integration](#-installation--plugin-integration) · [Storage Stack](#-storage-stack--path-layout) · [Lifecycle](#-memory-lifecycle-pipeline) · [Design Philosophy](#-design-philosophy-feature-removals)

---

Corti (corti): persistent, self-evolving memory layer for AI agents. Decouples runtime state from static weights. Stores state as diffable Markdown. Rebuilds high-performance Postgres/SQLite vector/BM25 indexes. Fully self-hosted.

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

1. Persona Agent vs. CLI Agent: Target audience = Persona Agents (e.g., Hermes Agent, OpenClaw Agent) ≠ CLI task-runners. Persona Agents require persistent background identity, preference awareness, context stability.

2. State-Weight Decoupling: Trillion-parameter static model weights cannot mutate for local projects. Runtime state must be decoupled from static weights.

3. Random Pre-Injection of Memory Fragments: Random pre-injection of memory fragments ➔ context. Matches human long-term memory: constant background context + targeted activation weights. Widens activation surface, prevents recall omission.

4. Runtime Epistemic Limits: Map vector spaces directly to context. Resolves runtime bottleneck: LLMs "do not know what they do not know". Resident memory ≠ On-demand query ("document lookup"). Memory requires residency to define identity.

---

⚡ Key Features

• Simplicity over Complexity (Why Not Knowledge Graphs?):
• Open-World Semantic Discrepancy: Open-world semantic parsing fails to converge. Code parsing has strict AST syntax, but natural language has systemic ambiguity. LLM parsing under AST/Safeguards generates naming collisions (e.g., "ABC Project" parsed sometimes as "ABC", other times as "ABC Project"), stalling graph construction. Formal ontology engineering (KBpedia, Wikipedia scale) is cost-prohibitive.
• Diminishing Search Utility: Graph traversal provides minimal marginal gain over raw keyword/semantic search. Open-world information lacks strict dependency chains; it relies on loose causality/inclusion. LLMs possess massive pre-trained associative spaces; passing raw keywords + semantic vectors triggers the correct associative touchpoints instantaneously without explicit graph edges.
• Memory-Knowledge Isomorphism & Limitation: Memory and knowledge are isomorphic at the root [1] [2]. Limitation: Corti does not currently distill memory into structured academic knowledge. Resolution: Semantic keywords/vectors are the most cost-effective trigger mechanism to activate LLM's pre-trained latent space.
• Theoretical Grounding: "Memory and knowledge share an isomorphic graph base $G = (V, E)$. The distinction is operational (meta-attribute variance), not structural (data format divergence)." [1]
• Dual Ingestion Paths:
• Silent Background Digestion: Automatic, silent background ingestion of conversation logs from active agent sessions.
• Explicit Agent PUT: Direct, programmatically triggered memory writes committed by the agent.
• Retrieval & Context Injection:
• Startup Fragment Pre-injection: Pre-loads random memory fragments at session startup ➔ resident context. Prepares cognitive triggers for keyword activation.
• Targeted Prompt Enrichment: Per-prompt targeted semantic search. Directly appends retrieved memory context to user input.
• Flexible Sharing & Isolation:
• Multi-dimensional namespace isolation across 5 axes: app_id, user_id, agent_id, project_id, session_id.
• Namespace mapping: identical setting values across axes ➔ memory sharing; distinct setting values ➔ absolute memory isolation.
• Markdown Source of Truth — Human-readable, diffable, Git-versioned .md files (~/.corti/). Rebuilds 100% from flat files.
• Sub-Second Cascade Watcher — Direct edits (VS Code, Obsidian, Neovim) ➔ automatic SQLite metadata & Postgres vector synchronization.
• Self-Evolving Offline Memory Engine (OME) — Background reflection loops compress raw conversation logs into atomic facts and dynamic profiles.
• Hybrid Postgres / PGLite Vector Search — Merges pgvector semantic similarity, BM25 keyword matching, and scalar SQL filters in single-query execution.
• Seamless Agent Integrations — Plugins for Hermes Agent, Claude Code, DeepSeek Harness (dsh), FastAPI HTTP endpoints, and CLI.

---

💾 Storage Stack & Path Layout

Three-piece embedded engine. Markdown = Single Source of Truth. SQLite + Postgres = Derived, 100% Rebuildable.

1. SQLite State Manager

• Role: Primary state engine, audit logger, and raw conversation buffer.
• Storage Mechanism: Collects raw conversation stream inputs. Stores them as structured JSON blobs / block objects representing unprocessed message arrays. Serves as canonical source for all downstream compiled memory artifacts.

2. PostgreSQL (PG) Memory Core

• Role: High-performance carrier substrate of persistent, query-ready memories.
• Storage Mechanism: Evaluates raw Markdown files, "chews" (digests) semantic structures, and compiles them into hierarchical Postgres table schemas:
• Episode: Individual Agent Session / Conversation segment (conversation streams chunked logically by topic boundaries).
• Facts: Refined and distilled semantic outputs extracted from