memorycoreclaw 2.0.0__tar.gz

memorycoreclaw-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MemoryCoreClaw Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memorycoreclaw-2.0.0/PKG-INFO

@@ -0,0 +1,398 @@
+Metadata-Version: 2.4
+Name: memorycoreclaw
+Version: 2.0.0
+Summary: A human-like memory engine for AI applications
+Author-email: MemoryCoreClaw Team <memorycoreclaw@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lcq225/MemoryCoreClaw
+Project-URL: Documentation, https://github.com/lcq225/MemoryCoreClaw#readme
+Project-URL: Repository, https://github.com/lcq225/MemoryCoreClaw.git
+Project-URL: Issues, https://github.com/lcq225/MemoryCoreClaw/issues
+Keywords: memory,ai,knowledge-graph,semantic-search,cognitive,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.0; extra == "embeddings"
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.0; extra == "visualization"
+Requires-Dist: networkx>=3.0; extra == "visualization"
+Dynamic: license-file
+
+# MemoryCoreClaw
+
+> A human-brain-inspired long-term memory engine for AI Agents
+
+[English](README.md) | [中文](README_zh.md)
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub release](https://img.shields.io/github/v/release/lcq225/MemoryCoreClaw.svg)](https://github.com/lcq225/MemoryCoreClaw/releases)
+
+---
+
+## Overview
+
+MemoryCoreClaw is a long-term memory engine that simulates human brain memory mechanisms, designed specifically for AI Agents. It implements cognitive science concepts including layered memory, forgetting curve, contextual triggers, and working memory, giving AI Agents the ability to "remember".
+
+### Why MemoryCoreClaw?
+
+Traditional AI Agents have limited conversation context and cannot remember user preferences or historical interactions over the long term. MemoryCoreClaw solves this problem:
+
+| Traditional Approach | MemoryCoreClaw |
+|---------------------|----------------|
+| Limited context window | Permanent memory storage |
+| Cannot remember user preferences | Remembers and associates user information |
+| Every conversation starts from zero | Automatically recalls relevant memories |
+| No knowledge accumulation | Knowledge graph continues to grow |
+
+---
+
+## Features
+
+### 🧠 Layered Memory
+- **Core Layer** (importance ≥ 0.9): Permanent retention, injected into context
+- **Important Layer** (0.7 ≤ importance < 0.9): Long-term retention
+- **Normal Layer** (0.5 ≤ importance < 0.7): Periodic consolidation
+- **Minor Layer** (importance < 0.5): May decay
+
+### 📉 Forgetting Curve
+Based on the Ebbinghaus forgetting curve model:
+- Memory strength decays over time
+- Access strengthens memory
+- Low-strength memories can be cleaned up
+
+### 🎯 Contextual Memory
+- Bind memories by people, location, emotion, activity
+- Context-triggered memory recall
+- Support for "What did we discuss at the coffee shop last time?"
+
+### 💼 Working Memory
+- Capacity limit (7±2 model)
+- Priority-based eviction strategy
+- TTL expiration mechanism
+
+### 🔗 Relation Learning
+- 28 standard relation types
+- Automatic relation inference
+- Knowledge graph visualization
+
+### 📤 Export
+- JSON format export
+- Markdown format export
+- Knowledge graph HTML visualization
+
+### 📊 Visualization (New in v2.0.0)
+
+- **Knowledge Graph** - Interactive D3.js force-directed graph with drag, zoom, and click-to-view details
+- **Statistics Report** - Memory count, categories, relation types visualization
+- **Memory Browser** - Searchable facts/lessons/relations list
+
+#### Screenshots
+
+**Knowledge Graph:**
+
+![Knowledge Graph](docs/images/knowledge_graph.png)
+
+**Statistics Report:**
+
+![Statistics Report](docs/images/stats_report.png)
+
+**Memory Browser:**
+
+![Memory Browser](docs/images/memory_browser.png)
+
+```bash
+# Generate visualizations
+python -m memorycoreclaw.utils.visualization
+
+# Or specify custom paths via environment variables
+MEMORY_DB_PATH=/path/to/memory.db MEMORY_OUTPUT_DIR=./output python -m memorycoreclaw.utils.visualization
+```
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install memorycoreclaw
+```
+
+### Basic Usage
+
+```python
+from memorycoreclaw import Memory
+
+# Initialize
+mem = Memory()
+
+# Remember facts
+mem.remember("Alice works at TechCorp", importance=0.8)
+mem.remember("Alice is skilled in Python", importance=0.7, category="technical")
+
+# Recall memories
+results = mem.recall("Alice")
+for r in results:
+    print(f"- {r['content']} (importance: {r['importance']})")
+
+# Learn lessons
+mem.learn(
+    action="Deployed without testing",
+    context="Production release",
+    outcome="negative",
+    insight="Always test before deployment",
+    importance=0.9
+)
+
+# Create relations
+mem.relate("Alice", "works_at", "TechCorp")
+mem.relate("Alice", "knows", "Bob")
+
+# Query relations
+relations = mem.get_relations("Alice")
+for rel in relations:
+    print(f"{rel['from_entity']} --[{rel['relation_type']}]--> {rel['to_entity']}")
+
+# Working memory
+mem.hold("current_task", "Writing documentation", priority=0.9)
+task = mem.retrieve("current_task")
+print(f"Current task: {task}")
+```
+
+---
+
+## Project Structure
+
+```
+MemoryCoreClaw/
+├── memorycoreclaw/          # Core code
+│   ├── core/                # Core engine
+│   │   ├── engine.py        # Memory engine
+│   │   └── memory.py        # Unified interface
+│   ├── cognitive/           # Cognitive modules
+│   │   ├── forgetting.py    # Forgetting curve
+│   │   ├── contextual.py    # Contextual memory
+│   │   └── working_memory.py # Working memory
+│   ├── retrieval/           # Retrieval modules
+│   │   ├── semantic.py      # Semantic search
+│   │   └── ontology.py      # Ontology
+│   ├── storage/             # Storage modules
+│   │   ├── database.py      # Database
+│   │   └── multimodal.py    # Multimodal
+│   └── utils/               # Utility modules
+│       ├── export.py        # Export
+│       └── visualization.py # Visualization
+├── docs/                    # Documentation
+│   ├── GETTING_STARTED.md   # Getting started
+│   ├── API.md               # API reference
+│   ├── ARCHITECTURE.md      # Architecture
+│   └── DEPLOYMENT.md        # Deployment guide
+├── examples/                # Example code
+├── tests/                   # Test cases
+└── config/                  # Configuration files
+```
+
+---
+
+## Documentation
+
+- [Getting Started](docs/GETTING_STARTED.md) - Quick start guide
+- [API Reference](docs/API.md) - Complete API documentation
+- [Architecture](docs/ARCHITECTURE.md) - System architecture
+- [Deployment](docs/DEPLOYMENT.md) - Installation and deployment guide
+
+---
+
+## Configuration
+
+Default configuration file `config/default.yaml`:
+
+```yaml
+# Database configuration
+database:
+  path: "~/.memorycoreclaw/memory.db"
+  encrypt: false
+
+# Memory layers
+layers:
+  core:
+    min_importance: 0.9
+    retention: permanent
+  important:
+    min_importance: 0.7
+    retention: long_term
+  normal:
+    min_importance: 0.5
+    retention: standard
+  minor:
+    min_importance: 0.0
+    retention: may_decay
+
+# Forgetting curve
+forgetting:
+  enabled: true
+  min_strength: 0.1
+  access_bonus: 1.1
+
+# Working memory
+working_memory:
+  capacity: 9
+  eviction_policy: lowest_priority
+```
+
+---
+
+## Integration Examples
+
+### LangChain Integration
+
+```python
+from langchain.memory import BaseMemory
+from memorycoreclaw import Memory
+
+class MemoryCoreClawMemory(BaseMemory):
+    """LangChain memory adapter"""
+    
+    def __init__(self, db_path=None):
+        self.mem = Memory(db_path=db_path)
+    
+    @property
+    def memory_variables(self):
+        return ["memory_context"]
+    
+    def load_memory_variables(self, inputs):
+        query = inputs.get("input", "")
+        memories = self.mem.recall(query, limit=5)
+        context = "\n".join([m["content"] for m in memories])
+        return {"memory_context": context}
+    
+    def save_context(self, inputs, outputs):
+        user_input = inputs.get("input", "")
+        ai_output = outputs.get("output", "")
+        self.mem.remember(f"User: {user_input}", importance=0.5)
+        self.mem.remember(f"AI: {ai_output}", importance=0.5)
+    
+    def clear(self):
+        pass
+
+# Usage
+from langchain.chat_models import ChatOpenAI
+from langchain.chains import ConversationChain
+
+memory = MemoryCoreClawMemory()
+llm = ChatOpenAI()
+chain = ConversationChain(llm=llm, memory=memory)
+```
+
+### RAG Enhancement
+
+```python
+from memorycoreclaw import Memory
+
+mem = Memory()
+
+def enhanced_rag_query(query):
+    # Recall relevant memories before RAG query
+    memories = mem.recall(query, limit=3)
+    context = "\n".join([m["content"] for m in memories])
+    
+    # Enhanced query
+    enriched_query = f"""
+Context memories:
+{context}
+
+User question: {query}
+"""
+    return enriched_query
+
+# Remember new information after query
+mem.remember(f"User asked about: {query}", importance=0.6)
+```
+
+---
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Memory storage | SQLite, supports millions of records |
+| Query latency | < 10ms (keyword search) |
+| Memory usage | < 50MB (100k memories) |
+| Concurrency | Multi-process read safe |
+
+---
+
+## Development
+
+### Setup Environment
+
+```bash
+# Clone repository
+git clone https://github.com/lcq225/MemoryCoreClaw.git
+cd MemoryCoreClaw
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or
+.\venv\Scripts\activate  # Windows
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+python tests/standalone_test.py
+```
+
+### Run Examples
+
+```bash
+# Basic example
+python examples/basic_usage.py
+
+# Knowledge graph example
+python examples/knowledge_graph.py
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please check [Contributing Guide](CONTRIBUTING.md).
+
+---
+
+## License
+
+[MIT License](LICENSE)
+
+---
+
+## Contact
+
+- GitHub: [https://github.com/lcq225/MemoryCoreClaw](https://github.com/lcq225/MemoryCoreClaw)
+- Issues: [https://github.com/lcq225/MemoryCoreClaw/issues](https://github.com/lcq225/MemoryCoreClaw/issues)
+
+---
+
+**MemoryCoreClaw** - Give AI Agents the power of memory 🧠