Unified Memory System for AI Agents
Give your AI persistent memory, multi-agent collaboration, and session continuity

Features • Quick Start • Installation • Usage • API • Contributing

AI agents forget everything between sessions. They can't share knowledge with other agents. They don't know what they were working on yesterday.

Neo-Cortex fixes this.

┌─────────────────────────────────────────────────────────────────┐
│                         NEO-CORTEX                               │
├───────────────┬───────────────┬───────────────┬────────────────┤
│   SHARED      │   SESSION     │   MEMORY      │    UNIFIED     │
│   MEMORY      │   CONTINUITY  │   HEALTH      │    STORAGE     │
│               │               │               │                │
│  Multi-agent  │   Session     │   Decay &     │   Local or     │
│  memory with  │   continuity  │   promotion   │   Cloud        │
│  convergence  │   tracking    │   system      │   backends     │
└───────────────┴───────────────┴───────────────┴────────────────┘

• Knowledge Base - Ingest markdown docs, search 920+ chunks across 20+ topics
• Shared Memory - Multi-agent memory with private, shared, and thread realms
• Session Continuity - Leave session notes for your future self across sessions
• Memory Health - Automatic decay, promotion, and deduplication
• Convergence Detection - Know when multiple agents agree (HARMONY/CONSENSUS)
• Web Dashboard - Visual UI for browsing knowledge, memory, sessions, agents, and health
• Dual Backend - ChromaDB for local, pgvector for cloud deployments
• Multiple Interfaces - CLI, MCP Server, REST API, Python SDK, Web Dashboard

# Clone the repo
git clone https://github.com/buckster123/NeoCortex.git
cd NeoCortex

# Install dependencies
pip install chromadb sentence-transformers fastapi uvicorn mcp

# Run the CLI
./cortex stats

# Post a memory to shared space
./cortex post "Neo-Cortex is operational!" --visibility shared

# Search your memories
./cortex search "operational"

# Save a session note for next time
./cortex session leave "Set up Neo-Cortex successfully" --priority HIGH

# Check health
./cortex health

• Python 3.10+
• ChromaDB (local) or PostgreSQL with pgvector (cloud)

git clone https://github.com/buckster123/NeoCortex.git
cd NeoCortex
pip install -r requirements.txt

# Core
pip install chromadb sentence-transformers

# For REST API
pip install fastapi uvicorn

# For MCP Server
pip install mcp

# For cloud (pgvector)
pip install asyncpg pgvector openai

# Statistics
./cortex stats

# Memory operations
./cortex post "Your message" --visibility shared --tags memory,important
./cortex search "query" --agent CLAUDE
./cortex agents
./cortex convergence "topic to check"

# Session notes
./cortex session leave "Session summary" --priority HIGH
./cortex session get

# Memory health
./cortex health
./cortex export > backup.json
./cortex import backup.json

from service.cortex_engine import CortexEngine

# Initialize
cortex = CortexEngine(backend='chroma')

# Shared Memory
cortex.memory_store("Hello world!", visibility="shared", tags=["greeting"])
results = cortex.memory_search("hello", n_results=5)

# Session Continuity
cortex.session_save(
    session_summary="Completed the setup",
    key_discoveries=["Neo-Cortex works great"],
    unfinished_business=["Add more features"],
    priority="HIGH"
)
sessions = cortex.session_recall(limit=5)

# Memory Health
report = cortex.health_report()
cortex.run_promotions("cortex_shared")

# Stats
stats = cortex.stats()
print(f"Total memories: {stats['total_memories']}")

Add to your ~/.claude.json:

{
  "mcpServers": {
    "neo-cortex": {
      "command": "/path/to/NeoCortex/cortex-mcp"
    }
  }
}

Then in Claude Code, you'll have access to 16 memory tools.

See INTEGRATE.md for a complete guide on adding neo-cortex session continuity to any project.

# Start the server
./cortex-api

# Or with uvicorn
uvicorn service.api_server:app --host 0.0.0.0 --port 8766

• OpenAPI docs at http://localhost:8766/docs
• Web dashboard at http://localhost:8766/ui

Three realms for organizing memories:

Memories flow through layers based on access patterns:

sensory (6h decay) → working (3d decay) → long_term (30d decay) → cortex (permanent)

High-access memories get promoted. Neglected memories decay.

Leave structured notes for session continuity:

cortex.session_save(
    session_summary="Built the authentication system",
    key_discoveries=["OAuth works better than JWT here"],
    unfinished_business=["Add refresh token support"],
    if_disoriented=["Check the auth/ folder", "Run tests first"],
    priority="HIGH"
)

Detect when multiple agents agree on something:

• HARMONY - 2 agents express similar ideas
• CONSENSUS - 3+ agents agree

result = cortex.memory_convergence("best database choice")
# Returns: {"convergence_type": "HARMONY", "converging_agents": ["agent1", "agent2"]}

One built-in agent, with runtime registration for custom agents:

Register your own with register_agent()!

Default backend. Zero configuration required.

cortex = CortexEngine(backend='chroma')

Data stored in ./data/chroma/

For production deployments with PostgreSQL.

cortex = CortexEngine(
    backend='pgvector',
    db_url='postgresql://user:pass@host:5432/db'
)

Requires the pgvector extension and OpenAI API key for embeddings.

Neo-Cortex can be used standalone or integrated into any AI agent framework via its Python SDK, MCP Server, or REST API.

from service.cortex_engine import CortexEngine

cortex = CortexEngine(backend='chroma')
cortex.memory_store("Hello from my agent!", visibility="shared")

┌─────────────────────────────────────────────────────────────────┐
│                        INTERFACES                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────────┐ │
│  │   CLI   │  │   MCP   │  │  REST   │  │    Python SDK       │ │
│  └────┬────┘  └────┬────┘  └────┬────┘  └──────────┬──────────┘ │
├───────┴────────────┴───────────┴───────────────────┴────────────┤
│                      CORTEX ENGINE                               │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────────┐  │
│  │ Knowledge │ │  Shared   │ │  Session  │ │  Memory Health  │  │
│  │  Engine   │ │  Memory   │ │  Engine   │ │     Engine      │  │
│  └───────────┘ └───────────┘ └───────────┘ └─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                      STORAGE ADAPTER                             │
│            ┌───────────────┐    ┌───────────────┐               │
│            │   ChromaDB    │    │   pgvector    │               │
│            │    (local)    │    │    (cloud)    │               │
│            └───────────────┘    └───────────────┘               │
└─────────────────────────────────────────────────────────────────┘

See ARCHITECTURE.md for detailed technical documentation.

Full API documentation available at:

• REST API: http://localhost:8766/docs (when running)
• docs/API.md - Complete endpoint reference
• docs/TOOLS.md - Tool schemas for function calling

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Fork the repo
# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes
# Run tests
python -m pytest tests/

# Commit
git commit -m "Add amazing feature"

# Push and create PR
git push origin feature/amazing-feature

MIT License - see LICENSE for details.

• Built with love by the Neo-Cortex contributors
• Powered by ChromaDB and pgvector
• Inspired by cognitive architectures and the need for AI agents to remember

Give your AI a memory. Give it Neo-Cortex.