+----------------------------------------------------------+
|                    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)         |
+-----------------+---------------+------------------------+

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

# 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]"

pip install -e .

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

# 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?"

python -m cory_mem.api.main

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

# 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

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()

from cory_mem.models.personal import PersonalMemory, PersonalCategory

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

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"
)

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"
)

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"),
    ]
)

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

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

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

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

# 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

# Lint with ruff
ruff check src/ tests/

# Format with ruff
ruff format src/ tests/

# Type checking with mypy
mypy src/cory_mem/

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