What is Memmimic

MemMimic is a persistent contextual memory system designed for AI assistants, leveraging the Model Context Protocol (MCP) to enhance memory retention across conversations. It integrates semantic search, cognitive classification, and narrative management, enabling a coherent understanding of user interactions over time.

Use cases

MemMimic can be utilized in various scenarios, including enhancing user interactions through personalized memory retention, project management by tracking critical milestones and reflections, and educational applications via tailored learning experiences using discourse analysis.

How to use

To get started, clone the MemMimic repository, create a virtual environment, and install the necessary dependencies for Python and Node.js. Next, configure the MCP settings within your AI assistant application and run the MemMimic server to manage and access memories using the provided API functions.

Key features

Key features of MemMimic include hybrid semantic and keyword memory search, automatic cognitive function classification, narrative generation from memory fragments, and self-reflective analysis. It offers advanced memory management tools like guided updates and pattern analysis for improved contextual understanding.

Where to use

MemMimic is suitable for deployment in AI-driven conversational agents, educational platforms, project management tools, and any application that requires sustained interaction and memory retention to improve user experience and context comprehension.

MemMimic

Persistent contextual memory system for AI assistants via Model Context Protocol (MCP).

What It Does

MemMimic provides AI assistants with persistent memory that survives across conversations. It combines semantic search, cognitive classification, and narrative management to maintain context over time.

Core capabilities:

• Store and retrieve memories with semantic + keyword search
• Automatic cognitive function classification (Control/Context/Data)
• Generate coherent narratives from memory fragments
• Self-reflective analysis and pattern recognition

Installation

Prerequisites

• Python 3.10+
• Node.js 16+

Setup

git clone https://github.com/xprooket/memmimic.git
cd memmimic

# Install Python dependencies
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Install Node.js dependencies for MCP server
cd src/memmimic/mcp
npm install

Claude Desktop Integration

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "memmimic": {
      "command": "node",
      "args": [
        "path/to/memmimic/src/memmimic/mcp/server.js"
      ],
      "env": {
        "PYTHONPATH": "path/to/memmimic/src"
      }
    }
  }
}

Quick Start

After installation, verify MemMimic is working with your first boot:

API Reference

MemMimic provides 11 essential tools organized by function:

🔍 Search

recall_cxd(query, function_filter?, limit?, db_name?)
Hybrid semantic + keyword memory search with cognitive filtering.

recall_cxd("project architecture decisions")
recall_cxd("error handling", function_filter="CONTROL", limit=3)

🧠 Memory Management

remember(content, memory_type?)
Store information with automatic cognitive classification.

remember("User prefers technical documentation over tutorials", "interaction")
remember("Project completed successfully", "milestone")

think_with_memory(input_text)
Process input with full memory context.

think_with_memory("How should we approach the database migration?")

status()
System health and memory statistics.

📖 Narrative Management

tales(query?, stats?, load?, category?, limit?)
Unified interface for tale management.

tales()                                    # List all tales
tales("project history")                   # Search tales
tales(stats=true)                         # Collection statistics
tales("intro", load=true)                 # Load specific tale

save_tale(name, content, category?, tags?)
Create or update narrative tales.

save_tale("project_overview", "Brief project description", "projects/main")

load_tale(name, category?)
Load specific tale by name.

delete_tale(name, category?, confirm?)
Delete tale with optional confirmation.

context_tale(query, style?, max_memories?)
Generate narrative from memory fragments.

context_tale("project introduction", "technical", 10)

🔧 Advanced Memory Operations

update_memory_guided(memory_id)
Update memory with Socratic guidance.

delete_memory_guided(memory_id, confirm?)
Delete memory with guided analysis.

analyze_memory_patterns()
Analyze usage patterns and content relationships.

🧘 Cognitive Tools

socratic_dialogue(query, depth?)
Self-questioning for deeper understanding.

socratic_dialogue("Why did this approach fail?", 3)

Architecture

src/memmimic/
├── memory/           # Core memory management
├── cxd/             # Cognitive classification system
├── tales/           # Narrative management
├── mcp/             # Model Context Protocol tools
└── api.py           # Main API interface

Key components:

• Memory Store: SQLite-based persistent storage
• CXD Classifier: Cognitive function detection (Control/Context/Data)
• Tale Manager: Narrative organization with v2.0 structure
• Semantic Search: Sentence transformers + FAISS vector store
• MCP Bridge: JavaScript-Python integration

Configuration

MemMimic works out of the box with sensible defaults. Advanced configuration available via:

• src/memmimic/cxd/config/cxd_config.yaml - Classification settings
• Environment variables: CXD_CONFIG, CXD_CACHE_DIR, CXD_MODE

Memory Types

• interaction - Conversational exchanges
• milestone - Important project events
• reflection - Analysis and insights
• synthetic - Pre-loaded knowledge
• socratic - Self-questioning dialogues

Tale Categories

• claude/core - Personal identity and principles
• claude/contexts - Collaboration contexts
• claude/insights - Accumulated wisdom
• projects/* - Technical documentation by project
• misc/* - General content

Development

# Run tests
cd src && python -m pytest tests/

# Test MCP integration
node src/memmimic/mcp/server.js

# Verify installation
python -c "from memmimic.api import create_memmimic; mm = create_memmimic(':memory:'); print(mm.status())"

Performance

• Memory retrieval: Sub-second for most queries
• Semantic indexing: ~1 second for 200+ memories
• Storage: SQLite with automatic optimization
• Caching: Persistent embeddings and vector indexes

⚠️ Usage Considerations

Claude API Rate Limits: MemMimic’s conversational and memory operations may approach Anthropic’s usage limits during intensive sessions. The system performs multiple API calls for:

• Memory classification and storage
• Semantic search operations
• Socratic dialogue generation
• Memory pattern analysis

Consider this for production deployments and monitor your usage accordingly.

Limitations

• Requires Model Context Protocol support
• Memory grows over time (no automatic cleanup)
• Semantic search quality depends on content similarity
• CXD classification optimized for English text
• May consume significant API quota during heavy usage

License

Apache License 2.0

Support

This is research-grade software. It works reliably for its intended use cases but isn’t enterprise production-ready. Use as foundation for more robust implementations.

For technical questions, see source code documentation.