{"id":28918373,"url":"https://github.com/xprooket/memmimic","last_synced_at":"2026-04-29T14:06:45.239Z","repository":{"id":299237099,"uuid":"1002142819","full_name":"xprooket/MemMimic","owner":"xprooket","description":"Contextual Memory Intelligence for AI Systems - Persistent memory, cognitive tools, and adaptive reasoning capabilities for LLMs (evolved from Clay-CXD)","archived":false,"fork":false,"pushed_at":"2025-06-15T13:24:53.000Z","size":4993,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-15T14:40:30.326Z","etag":null,"topics":["antrophic","claude-ai","context-persistence","contextual-memory","mcp","mcp-tools","memory-ai","prompt-engineering","semantic-classification","semantic-search"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xprooket.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-14T20:05:18.000Z","updated_at":"2025-06-15T13:24:56.000Z","dependencies_parsed_at":"2025-06-15T14:40:32.980Z","dependency_job_id":"dc81b924-7dfd-4dac-973f-b597f3b9a654","html_url":"https://github.com/xprooket/MemMimic","commit_stats":null,"previous_names":["xprooket/memmimic"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xprooket/MemMimic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xprooket%2FMemMimic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xprooket%2FMemMimic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xprooket%2FMemMimic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xprooket%2FMemMimic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xprooket","download_url":"https://codeload.github.com/xprooket/MemMimic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xprooket%2FMemMimic/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261224294,"owners_count":23126930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antrophic","claude-ai","context-persistence","contextual-memory","mcp","mcp-tools","memory-ai","prompt-engineering","semantic-classification","semantic-search"],"created_at":"2025-06-22T02:03:03.793Z","updated_at":"2026-04-29T14:06:45.234Z","avatar_url":"https://github.com/xprooket.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MemMimic\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)\n[![Version](https://img.shields.io/badge/version-1.0.0-brightgreen.svg)](https://github.com/xprooket/memmimic)\n\n\u003cdiv align=\"center\"\u003e\n\n![MemMimic Logo](docs/images/MemMimic.png)\n\n\u003c/div\u003e\n\nPersistent contextual memory system for AI assistants via Model Context Protocol (MCP).\n\n## What It Does\n\nMemMimic provides AI assistants with persistent memory that survives across conversations. It combines semantic search, cognitive classification, and narrative management to maintain context over time.\n\n**Core capabilities:**\n- Store and retrieve memories with semantic + keyword search\n- Automatic cognitive function classification (Control/Context/Data)\n- Generate coherent narratives from memory fragments\n- Self-reflective analysis and pattern recognition\n\n![MemMimic Architecture](docs/images/bluePrint.png)\n\n## Installation\n\n### Prerequisites\n- Python 3.10+\n- Node.js 16+\n\n### Setup\n```bash\ngit clone https://github.com/xprooket/memmimic.git\ncd memmimic\n\n# Install Python dependencies\npython -m venv venv\nsource venv/bin/activate  # Windows: venv\\Scripts\\activate\npip install -r requirements.txt\n\n# Install Node.js dependencies for MCP server\ncd src/memmimic/mcp\nnpm install\n```\n\n### Claude Desktop Integration\nAdd to your Claude Desktop MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"memmimic\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/memmimic/src/memmimic/mcp/server.js\"],\n      \"env\": {\n        \"PYTHONPATH\": \"path/to/memmimic/src\"\n      }\n    }\n  }\n}\n```\n## Quick Start\n\nAfter installation, verify MemMimic is working with your first boot:\n\n![MemMimic First Boot](docs/images/first-boot.png)\n## API Reference\n\nMemMimic provides 11 essential tools organized by function:\n\n### 🔍 Search\n**`recall_cxd(query, function_filter?, limit?, db_name?)`**\nHybrid semantic + keyword memory search with cognitive filtering.\n\n```\nrecall_cxd(\"project architecture decisions\")\nrecall_cxd(\"error handling\", function_filter=\"CONTROL\", limit=3)\n```\n\n### 🧠 Memory Management\n**`remember(content, memory_type?)`**\nStore information with automatic cognitive classification.\n\n```\nremember(\"User prefers technical documentation over tutorials\", \"interaction\")\nremember(\"Project completed successfully\", \"milestone\")\n```\n\n**`think_with_memory(input_text)`**\nProcess input with full memory context.\n\n```\nthink_with_memory(\"How should we approach the database migration?\")\n```\n\n**`status()`**\nSystem health and memory statistics.\n\n### 📖 Narrative Management\n**`tales(query?, stats?, load?, category?, limit?)`**\nUnified interface for tale management.\n\n```\ntales()                                    # List all tales\ntales(\"project history\")                   # Search tales\ntales(stats=true)                         # Collection statistics\ntales(\"intro\", load=true)                 # Load specific tale\n```\n\n**`save_tale(name, content, category?, tags?)`**\nCreate or update narrative tales.\n\n```\nsave_tale(\"project_overview\", \"Brief project description\", \"projects/main\")\n```\n\n**`load_tale(name, category?)`**\nLoad specific tale by name.\n\n**`delete_tale(name, category?, confirm?)`**\nDelete tale with optional confirmation.\n\n**`context_tale(query, style?, max_memories?)`**\nGenerate narrative from memory fragments.\n\n```\ncontext_tale(\"project introduction\", \"technical\", 10)\n```\n\n### 🔧 Advanced Memory Operations\n**`update_memory_guided(memory_id)`**\nUpdate memory with Socratic guidance.\n\n**`delete_memory_guided(memory_id, confirm?)`**\nDelete memory with guided analysis.\n\n**`analyze_memory_patterns()`**\nAnalyze usage patterns and content relationships.\n\n### 🧘 Cognitive Tools\n**`socratic_dialogue(query, depth?)`**\nSelf-questioning for deeper understanding.\n\n```\nsocratic_dialogue(\"Why did this approach fail?\", 3)\n```\n\n## Architecture\n\n```\nsrc/memmimic/\n├── memory/           # Core memory management\n├── cxd/             # Cognitive classification system\n├── tales/           # Narrative management\n├── mcp/             # Model Context Protocol tools\n└── api.py           # Main API interface\n```\n\n**Key components:**\n- **Memory Store**: SQLite-based persistent storage\n- **CXD Classifier**: Cognitive function detection (Control/Context/Data)\n- **Tale Manager**: Narrative organization with v2.0 structure\n- **Semantic Search**: Sentence transformers + FAISS vector store\n- **MCP Bridge**: JavaScript-Python integration\n\n## Configuration\n\nMemMimic works out of the box with sensible defaults. Advanced configuration available via:\n\n- `src/memmimic/cxd/config/cxd_config.yaml` - Classification settings\n- Environment variables: `CXD_CONFIG`, `CXD_CACHE_DIR`, `CXD_MODE`\n\n## Memory Types\n\n- `interaction` - Conversational exchanges\n- `milestone` - Important project events\n- `reflection` - Analysis and insights\n- `synthetic` - Pre-loaded knowledge\n- `socratic` - Self-questioning dialogues\n\n## Tale Categories\n\n- `claude/core` - Personal identity and principles\n- `claude/contexts` - Collaboration contexts\n- `claude/insights` - Accumulated wisdom\n- `projects/*` - Technical documentation by project\n- `misc/*` - General content\n\n## Development\n\n```bash\n# Run tests\ncd src \u0026\u0026 python -m pytest tests/\n\n# Test MCP integration\nnode src/memmimic/mcp/server.js\n\n# Verify installation\npython -c \"from memmimic.api import create_memmimic; mm = create_memmimic(':memory:'); print(mm.status())\"\n```\n\n## Performance\n\n- **Memory retrieval**: Sub-second for most queries\n- **Semantic indexing**: ~1 second for 200+ memories\n- **Storage**: SQLite with automatic optimization\n- **Caching**: Persistent embeddings and vector indexes\n\n## ⚠️ Usage Considerations\n\n**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:\n- Memory classification and storage\n- Semantic search operations\n- Socratic dialogue generation\n- Memory pattern analysis\n\nConsider this for production deployments and monitor your usage accordingly.\n\n## Limitations\n\n- Requires Model Context Protocol support\n- Memory grows over time (no automatic cleanup)\n- Semantic search quality depends on content similarity\n- CXD classification optimized for English text\n- May consume significant API quota during heavy usage\n\n## License\n\nApache License 2.0\n\n## Support\n\nThis 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.\n\nFor technical questions, see source code documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxprooket%2Fmemmimic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxprooket%2Fmemmimic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxprooket%2Fmemmimic/lists"}