Codex Memory

A high-performance, minimal memory storage service with MCP (Model Context Protocol) interface for Claude Desktop integration. Codex Memory provides reliable, deduplicated storage with automatic chunking for large content.

🚀 Features

Core Capabilities

🗄️ Reliable Text Storage - PostgreSQL-backed storage with ACID compliance
🔒 Content Deduplication - SHA-256 hash-based automatic deduplication
📄 Smart File Chunking - Automatic chunking with configurable overlap for large files
🏷️ Tag-Based Organization - Flexible tagging system for categorization
🔗 Parent-Child Relationships - Maintains relationships between chunks and source documents
🤖 MCP Integration - Native Model Context Protocol support for Claude Desktop

Technical Features

Connection Pooling - Optimized connection management (20 connections)
Async/Await Architecture - Built on Tokio for high concurrency
Comprehensive Error Handling - Proper Result types throughout
UTF-8 Safe Chunking - Respects character boundaries in all operations
Full-Text Search - PostgreSQL-powered search capabilities

🤝 Works With Codex-Dreams

Shared Database - Uses the same PostgreSQL database for seamless integration
Complementary Roles - Codex Memory for storage, Codex-Dreams for AI analysis
Zero Configuration - Install both applications, they work together automatically
Enhanced Workflow - Store with Codex Memory, analyze with Codex-Dreams

📋 Architecture

Codex follows a modular architecture focused on simplicity and reliability:

┌─────────────────────────────────────────────────────────────────┐
│                      Codex Memory Architecture                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐ │
│  │   CLI Interface │    │   MCP Server    │    │  PostgreSQL │ │
│  │                 │    │                 │    │  Database   │ │
│  │  • store        │◄──►│  • JSON-RPC 2.0 │◄──►│             │ │
│  │  • get          │    │  • 5 MCP Tools  │    │  • Indexes  │ │
│  │  • stats        │    │  • stdio I/O    │    │  • ACID     │ │
│  │  • setup        │    │                 │    │             │ │
│  └─────────────────┘    └─────────────────┘    └─────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🧠 Companion Application: Codex-Dreams

Codex Memory works seamlessly with Codex-Dreams, a companion application that adds advanced cognitive processing capabilities:

Memory Insights: Generate intelligent insights from stored memories using LLM analysis
Pattern Recognition: Identify trends and connections across your stored content
Memory Consolidation: Advanced memory tiering and summarization
Semantic Analysis: Deep understanding and categorization of memories

Codex-Dreams reads from the same database as Codex Memory, creating a powerful two-tier system:

Codex Memory (this project): Fast, reliable storage and retrieval
Codex-Dreams: Advanced AI-powered analysis and insights

Get started with both: Install Codex Memory first, then add Codex-Dreams for cognitive features.

🛠️ Installation

Prerequisites

Rust 1.70 or higher
PostgreSQL 14 or higher
Claude Desktop (optional, for MCP integration)

Quick Start

# Clone the repository
git clone https://github.com/Ladvien/codex-memory.git
cd codex-memory

# Set up environment
cp .env.example .env
# Edit .env with your database credentials

# Install
cargo install --path . --force

# Setup database (creates database, user, and tables)
codex-memory setup

# Run MCP server for Claude Desktop
codex-memory mcp

Environment Configuration

Create a .env file with:

DATABASE_URL=postgresql://codex_user:codex_pass@localhost:5432/codex_db
RUST_LOG=info  # Optional: debug, info, warn, error

📖 Usage

Command Line Interface

# Store content with metadata
codex-memory store "Your content here" \
  --context "Meeting notes" \
  --summary "Q4 planning discussion" \
  --tags "meeting,planning,q4"

# Retrieve content by ID
codex-memory get <UUID>

# View storage statistics
codex-memory stats

# Run MCP server for Claude Desktop
codex-memory mcp

🔄 Companion Workflow with Codex-Dreams

For the full cognitive memory experience, use both applications together:

# 1. Store memories with Codex Memory (fast, reliable)
codex-memory store "Research findings on neural networks" \
  --context "AI Research" \
  --summary "Key insights from latest papers" \
  --tags "ai,research,neural-networks"

# 2. Generate insights with Codex-Dreams (AI-powered analysis)
codex-dreams generate-insights --time-period week
codex-dreams show-insights --limit 5
codex-dreams search-insights "neural networks" --limit 10

💡 Workflow Tip: Use Codex Memory for day-to-day storage and retrieval, then run Codex-Dreams periodically to generate insights and discover patterns across your stored memories.

MCP Tools (Claude Desktop)

Codex provides 5 MCP tools:

Tool	Description	Parameters
`store_memory`	Store text with metadata	content, context, summary, tags
`get_memory`	Retrieve by ID	id (UUID)
`delete_memory`	Remove by ID	id (UUID)
`get_statistics`	Get storage stats	none
`store_file`	Chunk and store files	file_path, chunk_size, overlap, tags

Claude Desktop Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "codex-memory": {
      "command": "/path/to/codex-memory",
      "args": ["mcp"],
      "env": {
        "DATABASE_URL": "postgresql://codex_user:codex_pass@localhost:5432/codex_db"
      }
    }
  }
}

🏗️ API

Rust API Example

use codex_memory::{Storage, Config, create_pool};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create connection pool
    let config = Config::from_env()?;
    let pool = create_pool(&config.database_url).await?;
    let storage = Arc::new(Storage::new(pool));
    
    // Store content
    let id = storage.store(
        "Content to store",
        "Context information".to_string(),
        "Brief summary".to_string(),
        Some(vec!["tag1".to_string(), "tag2".to_string()])
    ).await?;
    
    // Retrieve content
    if let Some(memory) = storage.get(id).await? {
        println!("Retrieved: {}", memory.content);
    }
    
    Ok(())
}

Database Schema

CREATE TABLE memories (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    content TEXT NOT NULL,
    content_hash VARCHAR(64) NOT NULL UNIQUE,
    context TEXT NOT NULL,
    summary TEXT NOT NULL,
    metadata JSONB DEFAULT '{}',
    tags TEXT[] DEFAULT '{}',
    chunk_index INTEGER DEFAULT NULL,
    total_chunks INTEGER DEFAULT NULL,
    parent_id UUID DEFAULT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

🧪 Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test suite
cargo test integration
cargo test unit
cargo test edge_cases

# Run with coverage (requires cargo-tarpaulin)
cargo tarpaulin --out Html

🚀 Performance

Benchmarks

Operation	Performance	Notes
Store (small)	~5ms	Including deduplication
Store (chunked)	~10ms/chunk	8KB chunks
Retrieve	~2ms	By UUID
Delete	~3ms	Single operation
Statistics	~15ms	Aggregate query

Optimization Features

Connection pooling (20 connections, 2 min)
Prepared statements
Index optimization (B-tree and GIN indexes)
SHA-256 content deduplication
Async I/O throughout

🔧 Development

Building from Source

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Run clippy lints
cargo clippy -- -D warnings

# Format code
cargo fmt

# Security audit
cargo audit

Project Structure

codex-memory/
├── src/
│   ├── main.rs           # CLI entry point
│   ├── lib.rs            # Library exports
│   ├── storage.rs        # Core storage logic
│   ├── models.rs         # Data structures
│   ├── database/         # Database operations
│   ├── mcp_server/       # MCP protocol implementation
│   └── chunking.rs       # File chunking logic
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── edge_cases/       # Edge case tests
└── migrations/           # Database migrations

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

Codex-Dreams - Companion app for AI-powered memory insights and cognitive processing
Claude Desktop - Anthropic's Claude Desktop application
MCP Specification - Model Context Protocol specification

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: See ARCHITECTURE.md for detailed system design

🙏 Acknowledgments

Built with Rust and PostgreSQL
MCP protocol for LLM integration
Tokio for async runtime
SQLx for database operations

💡 Pro Tip: Maximize your memory system by using both applications together. Codex Memory handles fast storage and retrieval, while Codex-Dreams adds intelligent analysis and insights generation.

codex-memory 2.1.2