cory-mem

A comprehensive memory system for Claude-based AI projects enabling learning, self-organization, and persistent context across sessions.

Overview

cory-mem provides a personal memory layer for AI assistants, allowing them to remember context, learn from interactions, and maintain persistent knowledge across sessions. It combines short-term session memory with long-term semantic storage, enabling natural context retrieval through hybrid search.

Features

• Short-term (Session) Memory: Captures conversation context with automatic promotion to long-term storage
• Long-term (Persistent) Memory: Durable storage with version history and conflict detection
• Semantic Search with FAISS + Keyword Search: Hybrid retrieval combining vector similarity and TF-IDF
• Pluggable Embedding Providers: Support for local (sentence-transformers), OpenAI, Claude, and Ollama
• MCP Server Integration: Native support for Claude Code and MCP-compatible clients
• REST API with FastAPI: Full CRUD operations, search endpoints, and analytics
• Conflict Detection & Resolution: Automatic detection of duplicates, contradictions, and merge candidates
• Version History & Backup: Complete audit trail with point-in-time restoration
• Automated Maintenance Scheduling: Background jobs for sync, pruning, and index optimization

Architecture

+----------------------------------------------------------+
|                    Client Layer                          |
+----------------------------------------------------------+
|  Native Python  |   MCP Server    |     REST API         |
|    Library      |  (Claude Code)  |    (FastAPI)         |
+-----------------+-----------------+----------------------+
                           |
+----------------------------------------------------------+
|                   Core Services                          |
+----------------------------------------------------------+
|  Memory Manager | Search Engine | Scheduler | Conflict   |
|                 | (Hybrid)      |           | Resolver   |
+-----------------+---------------+-----------+------------+
                           |
+----------------------------------------------------------+
|                   Storage Layer                          |
+----------------------------------------------------------+
|  JSON Storage   |  FAISS Index  |  Version History       |
|  (Long-term)    |  (Vectors)    |  (Audit Trail)         |
+-----------------+---------------+------------------------+

Component Diagram

graph TB
    subgraph "Client Interfaces"
        A[Python Library]
        B[MCP Server]
        C[REST API]
    end

    subgraph "Core Services"
        D[Memory Manager]
        E[Search Engine]
        F[Scheduler]
        G[Conflict Resolver]
        H[Lifecycle Tracker]
    end

    subgraph "Embedding Providers"
        I[Local<br/>sentence-transformers]
        J[OpenAI]
        K[Claude]
        L[Ollama]
    end

    subgraph "Storage"
        M[(JSON Files)]
        N[(FAISS Index)]
        O[(Version History)]
    end

    A --> D
    B --> D
    C --> D

    D --> E
    D --> F
    D --> G
    D --> H

    E --> I
    E --> J
    E --> K
    E --> L

    E --> N
    D --> M
    D --> O

Installation

Using uv (Recommended)

# Clone the repository
git clone https://github.com/yourusername/cory-mem.git
cd cory-mem

# Install with uv
uv pip install -e .

# Install with development dependencies
uv pip install -e ".[dev]"

Using pip

pip install -e .

Dependencies

Core dependencies:

• pydantic>=2.0 - Data validation
• fastapi>=0.109 - REST API
• faiss-cpu - Vector similarity search
• sentence-transformers - Local embeddings
• mcp - Model Context Protocol
• apscheduler>=3.10 - Background scheduling

Quick Start

Using MCP Server with Claude Code

Add to your Claude Code MCP settings (~/.claude/mcp.json):

{
  "mcpServers": {
    "cory-mem": {
      "command": "python",
      "args": ["-m", "cory_mem.mcp"],
      "env": {
        "CORY_MEM_EMBEDDING_PROVIDER": "local"
      }
    }
  }
}

Then in Claude Code, you can use memory tools:

# Store a memory
Use memory_inject to save: "User prefers Python for backend development"

# Retrieve relevant context
Use memory_retrieve with query: "What programming languages does the user prefer?"

Using REST API

Start the API server:

python -m cory_mem.api.main

Or with uvicorn:

uvicorn cory_mem.api.main:app --host 127.0.0.1 --port 8420

API endpoints:

# Create a memory
curl -X POST http://localhost:8420/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User works at Anthropic as an engineer",
    "memory_type": "personal",
    "tags": ["employment", "career"]
  }'

# Search memories
curl -X POST http://localhost:8420/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "where does the user work?",
    "limit": 5
  }'

# Health check
curl http://localhost:8420/health

Using Python Library Directly

from cory_mem.core.memory_manager import MemoryManager, MemoryContext
from cory_mem.models.base import MemoryType
from cory_mem.config import get_config

# Initialize
config = get_config()
manager = MemoryManager(config)

# Start a session
session = manager.start_session()

# Add to short-term memory
manager.add_to_session(
    session.session_id,
    content="User asked about Python async patterns",
    category="interaction"
)

# Inject to long-term memory
memory = manager.inject(
    content="User is an experienced Python developer specializing in async programming",
    memory_type=MemoryType.PERSONAL,
    context=MemoryContext(
        source="conversation",
        tags=["python", "skills", "async"],
        confidence=0.9
    )
)

# Search memories
results = manager.search(
    query="What are the user's programming skills?",
    memory_types=[MemoryType.PERSONAL, MemoryType.KNOWLEDGE],
    limit=10
)

# Get context for conversation
context = manager.get_context_for_conversation(
    query="Help me with async Python",
    session_id=session.session_id,
    max_memories=10
)
print(context.to_text())

# Sync session to long-term storage
sync_result = manager.sync_session_to_long_term(session.session_id)

# Get statistics
stats = manager.get_stats()

Memory Types

Personal Memories

Stores information about the user: preferences, relationships, employment history.

from cory_mem.models.personal import PersonalMemory, PersonalCategory

memory = PersonalMemory(
    content="User prefers dark mode and vim keybindings",
    category=PersonalCategory.PREFERENCE,
)

Categories:

• PREFERENCE - User preferences and settings
• EMPLOYMENT - Work history and job information
• RELATIONSHIP - Family, friends, colleagues
• BACKGROUND - Education, hometown, biography
• GENERAL - Other personal information

Knowledge Base

Facts, skills, and domain-specific knowledge.

from cory_mem.models.knowledge import KnowledgeMemory, KnowledgeDomain

memory = KnowledgeMemory(
    content="FAISS uses product quantization for efficient similarity search",
    domain=KnowledgeDomain.TECHNOLOGY,
    knowledge_type="fact"
)

Domains:

• TECHNOLOGY, SCIENCE, BUSINESS, ARTS, HEALTH, EDUCATION, GENERAL

Interactions

Conversation summaries and interaction patterns.

from cory_mem.models.interaction import InteractionMemory, InteractionOutcome

memory = InteractionMemory(
    content="Helped user debug a race condition in their async code",
    outcome=InteractionOutcome.SUCCESSFUL,
    sentiment="positive"
)

Projects

Goals, milestones, and progress tracking.

from cory_mem.models.project import ProjectMemory, ProjectStatus, Milestone

memory = ProjectMemory(
    content="Build a personal memory system for AI",
    status=ProjectStatus.IN_PROGRESS,
    milestones=[
        Milestone(name="Design architecture", status="completed"),
        Milestone(name="Implement storage layer", status="completed"),
        Milestone(name="Add MCP integration", status="in_progress"),
    ]
)

Configuration

Configuration via environment variables (prefix: CORY_MEM_):

Variable	Default	Description
CORY_MEM_MEMORY_BASE_PATH	~/.cory-mem/memory	Base directory for storage
CORY_MEM_EMBEDDING_PROVIDER	local	Embedding provider: local, openai, claude, ollama
CORY_MEM_EMBEDDING_MODEL	all-MiniLM-L6-v2	Model name for embeddings
CORY_MEM_EMBEDDING_DIMENSION	384	Vector dimension size
CORY_MEM_OPENAI_API_KEY	-	OpenAI API key (if using OpenAI provider)
CORY_MEM_ANTHROPIC_API_KEY	-	Anthropic API key (if using Claude provider)
CORY_MEM_OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
CORY_MEM_SESSION_TTL_HOURS	24	Session expiration time
CORY_MEM_MAX_SESSION_ENTRIES	1000	Max entries per session
CORY_MEM_SEARCH_DEFAULT_LIMIT	10	Default search result count
CORY_MEM_SEARCH_SIMILARITY_THRESHOLD	0.5	Minimum similarity score
CORY_MEM_SYNC_INTERVAL_MINUTES	60	Sync job interval
CORY_MEM_PRUNE_INTERVAL_HOURS	24	Prune job interval
CORY_MEM_MAINTENANCE_DAY	sunday	Weekly maintenance day
CORY_MEM_API_HOST	127.0.0.1	API server host
CORY_MEM_API_PORT	8420	API server port

Or use a .env file:

CORY_MEM_EMBEDDING_PROVIDER=openai
CORY_MEM_OPENAI_API_KEY=sk-...
CORY_MEM_API_PORT=9000

API Reference

Memories API (/api/v1/memories)

Method	Endpoint	Description
POST	/memories	Create a new memory
GET	/memories/{id}	Get memory by ID
PUT	/memories/{id}	Update a memory
DELETE	/memories/{id}	Delete a memory
GET	/memories	List memories with filtering

Search API (/api/v1/search)

Method	Endpoint	Description
POST	/search	Hybrid search (semantic + keyword)
POST	/search/semantic	Semantic-only search
POST	/search/keyword	Keyword-only search
POST	/search/tags	Search by tags

Scheduler API (/api/v1/scheduler)

Method	Endpoint	Description
GET	/scheduler/jobs	List scheduled jobs
POST	/scheduler/jobs/{type}/run	Trigger job manually
GET	/scheduler/history	Get job execution history

Versioning API (/api/v1/versioning)

Method	Endpoint	Description
GET	/versioning/{id}/history	Get version history
POST	/versioning/{id}/restore/{version}	Restore to version
POST	/versioning/backup	Create backup

Analytics API (/api/v1/analytics)

Method	Endpoint	Description
GET	/analytics/stats	Get memory statistics
GET	/analytics/lifecycle	Get lifecycle metrics

Interactive documentation available at /docs (Swagger UI) and /redoc.

MCP Tools

Available tools when using the MCP server:

Tool	Description
memory_inject	Add new information to long-term memory
memory_retrieve	Get relevant context for a query
memory_update	Modify an existing memory
memory_search	Search with full options (semantic + keyword)
memory_delete	Remove a memory (soft or hard delete)

MCP Resources

Resource URI	Description
memory://stats	Memory system statistics
memory://recent	Recently accessed memories
memory://type/{type}	Memories by type

MCP Prompts

Prompt	Description
memory-context	Get relevant memory context for a topic
memory-summary	Get a summary of stored memories

Internal Operations

Memory Lifecycle

sequenceDiagram
    participant C as Client
    participant M as MemoryManager
    participant S as SearchEngine
    participant ST as Storage
    participant I as FAISS Index

    C->>M: inject(content, type)
    M->>M: Validate & create Memory
    M->>ST: Store JSON
    M->>S: Generate embedding
    S->>I: Add to index
    M-->>C: Return memory

    C->>M: search(query)
    M->>S: hybrid_search(query)
    S->>S: Generate query embedding
    S->>I: Vector similarity search
    S->>S: Keyword TF-IDF search
    S->>S: Merge & rank results
    S-->>M: Return results
    M-->>C: Return memories

Conflict Resolution Flow

flowchart TD
    A[New Memory] --> B{Compute Similarity}
    B --> C{Similarity >= 0.95?}
    C -->|Yes| D[DUPLICATE]
    C -->|No| E{Similarity >= 0.85?}
    E -->|Yes| F{Same Category?}
    F -->|Yes| G[CONTRADICTION]
    F -->|No| H{Time Diff > 24h?}
    H -->|Yes| I[OUTDATED]
    H -->|No| J{Similarity >= 0.75?}
    E -->|No| J
    J -->|Yes| K[MERGE_CANDIDATE]
    J -->|No| L[No Conflict]

    D --> M{Confidence >= 0.8?}
    I --> M
    G --> N[Manual Review]
    K --> O{Confidence >= 0.9?}

    M -->|Yes| P[Auto: Keep Newer]
    M -->|No| N
    O -->|Yes| Q[Auto: Merge]
    O -->|No| N

Scheduler Job Flow

sequenceDiagram
    participant S as Scheduler
    participant J as JobRunner
    participant M as MemoryManager
    participant H as JobHistory

    S->>S: Check job schedule
    S->>J: Execute job

    alt SYNC_SHORT_TO_LONG
        J->>M: sync_session_to_long_term()
        M-->>J: SyncResult
    else PRUNE_EXPIRED
        J->>M: cleanup()
        M-->>J: Cleanup stats
    else MAINTENANCE
        J->>M: Merge duplicates
        J->>M: Optimize indexes
    else BACKUP
        J->>M: Create backup
    end

    J->>H: Record result
    H-->>S: Job complete

Development

Running Tests

# Run all tests with coverage
pytest

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/e2e/

# Run with verbose output
pytest -v --cov=src/cory_mem --cov-report=term-missing

Code Quality

# Lint with ruff
ruff check src/ tests/

# Format with ruff
ruff format src/ tests/

# Type checking with mypy
mypy src/cory_mem/

Project Structure

cory-mem/
├── src/cory_mem/
│   ├── api/              # FastAPI REST endpoints
│   │   ├── routers/      # Route handlers
│   │   └── schemas/      # Pydantic request/response models
│   ├── core/             # Core business logic
│   │   ├── memory_manager.py
│   │   ├── short_term.py
│   │   ├── long_term.py
│   │   ├── conflict_resolver.py
│   │   └── lifecycle_tracker.py
│   ├── embeddings/       # Embedding providers
│   │   ├── base.py
│   │   ├── local.py
│   │   ├── openai.py
│   │   └── claude.py
│   ├── mcp/              # MCP server integration
│   │   ├── server.py
│   │   ├── tools.py
│   │   └── resources.py
│   ├── models/           # Data models
│   │   ├── base.py
│   │   ├── personal.py
│   │   ├── knowledge.py
│   │   ├── interaction.py
│   │   └── project.py
│   ├── scheduler/        # Background job scheduling
│   │   ├── jobs.py
│   │   └── runner.py
│   ├── search/           # Hybrid search engine
│   │   ├── engine.py
│   │   └── keyword.py
│   ├── storage/          # Persistence layer
│   │   ├── json_storage.py
│   │   └── faiss_index.py
│   ├── versioning/       # Version control & backup
│   │   ├── history.py
│   │   ├── diff.py
│   │   └── backup.py
│   └── config.py         # Configuration management
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── scripts/
│   └── hooks/            # Claude Code hooks
├── pyproject.toml
└── README.md

License

MIT License - see LICENSE for details.

---

Built for seamless integration with Claude and the Model Context Protocol ecosystem.