kuzu-memory


Namekuzu-memory JSON
Version 1.2.3 PyPI version JSON
download
home_pageNone
SummaryLightweight, embedded graph-based memory system for AI applications
upload_time2025-10-06 21:25:23
maintainerNone
docs_urlNone
authorNone
requires_python>=3.11
licenseMIT
keywords ai memory graph database kuzu chatbot llm
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # KuzuMemory

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/kuzu-memory/kuzu-memory/workflows/Tests/badge.svg)](https://github.com/kuzu-memory/kuzu-memory/actions)

**Lightweight, embedded graph-based memory system for AI applications**

KuzuMemory provides fast, offline memory capabilities for chatbots and AI systems without requiring LLM calls. It uses pattern matching and local graph storage to remember and recall contextual information.

## ✨ Key Features

- **🧠 Cognitive Memory Model** - Based on human memory psychology (SEMANTIC, PROCEDURAL, EPISODIC, etc.)
- **πŸš€ No LLM Dependencies** - Operates using pattern matching and local NER only
- **⚑ Fast Performance** - <3ms memory recall, <8ms memory generation (verified with Kuzu)
- **πŸ’Ύ Embedded Database** - Single-file Kuzu graph database
- **πŸ”„ Git-Friendly** - Database files <10MB, perfect for version control
- **πŸ”Œ Simple API** - Just two methods: `attach_memories()` and `generate_memories()`
- **🌐 Cross-Platform** - Standardized cognitive types shared with TypeScript implementation
- **πŸ“± Offline First** - Works completely without internet connection
- **πŸ”§ MCP Ready** - Native Claude Desktop integration with async learning support
- **πŸ€– Hook Compatible** - Ready for claude-mpm hook integration

## πŸš€ Quick Start

### Installation

```bash
# Install via pipx (recommended for CLI usage)
pipx install kuzu-memory

# Or install via pip
pip install kuzu-memory

# For development
pip install kuzu-memory[dev]
```

**Now available on PyPI!** KuzuMemory v1.1.0 is published and ready for production use.

### AI Integration

KuzuMemory can be integrated with various AI systems following the **ONE PATH** principle:

```bash
# List available integrations
kuzu-memory install list

# Install Claude Code integration (project-specific memory)
kuzu-memory install add claude-code

# Install Claude Desktop integration (global memory)
kuzu-memory install add claude-desktop

# Install Auggie integration
kuzu-memory install add auggie

# Install universal integration files
kuzu-memory install add universal

# Check installation status
kuzu-memory install status
```

**Primary Installers** (ONE path for each AI system):
- `claude-code` - Claude Code IDE integration (project-specific memory isolation)
- `claude-desktop` - Claude Desktop app (global memory across all conversations)
- `auggie` - Auggie AI integration
- `universal` - Universal integration files

**Key Differences**:

**Claude Code** (`claude-code`):
- **Configuration**: Creates `.kuzu-memory/config.yaml` in project directory
- **Database**: Initializes project database in `.kuzu-memory/memorydb/`
- **Memory Scope**: Each project has isolated memory
- **Use Case**: Project-specific context and memories
- **Sharing**: Memory can be committed to git for team collaboration

**Claude Desktop** (`claude-desktop`):
- **Configuration**: Creates `~/.kuzu-memory/config.yaml` in home directory
- **Database**: Initializes global database in `~/.kuzu-memory/memorydb/`
- **Memory Scope**: Shared across all Claude Desktop conversations
- **Use Case**: Personal knowledge base and preferences
- **Installation**: Auto-detects pipx or home directory installation

**Installation Options:**
- `--force` - Force reinstall even if already installed (overwrites existing config)
- `--dry-run` - Preview changes without modifying files
- `--verbose` - Show detailed installation steps
- `--mode [auto|pipx|home]` - Override auto-detection (claude-desktop only)
- `--backup-dir PATH` - Custom backup directory
- `--memory-db PATH` - Custom memory database location

**Automatic Initialization**:
- Configuration files are created automatically during installation
- Database is initialized automatically
- Existing configurations are preserved (use `--force` to overwrite)
- Backups are created when overwriting existing files

See [Claude Setup Guide](docs/CLAUDE_SETUP.md) for detailed instructions on Claude Desktop and Claude Code integration.

> **Note**: Previous installer names (e.g., `claude-desktop-pipx`, `claude-desktop-home`) still work but show deprecation warnings.

### Basic Usage

```python
from kuzu_memory import KuzuMemory

# Initialize memory system
memory = KuzuMemory()

# Store memories from conversation
memory.generate_memories("""
User: My name is Alice and I work at TechCorp as a Python developer.
Assistant: Nice to meet you, Alice! Python is a great choice for development.
""")

# Retrieve relevant memories
context = memory.attach_memories("What's my name and where do I work?")

print(context.enhanced_prompt)
# Output includes: "Alice", "TechCorp", "Python developer"
```

### CLI Usage

```bash
# Initialize memory database
kuzu-memory init

# Store a memory
kuzu-memory memory store "I prefer using TypeScript for frontend projects"

# Recall memories
kuzu-memory memory recall "What do I prefer for frontend?"

# Enhance a prompt
kuzu-memory memory enhance "What's my coding preference?"

# View statistics
kuzu-memory status
```

## πŸ“– Core Concepts

### Cognitive Memory Types

KuzuMemory uses a cognitive memory model inspired by human memory systems:

- **SEMANTIC** - Facts and general knowledge (never expires)
- **PROCEDURAL** - Instructions and how-to content (never expires)
- **PREFERENCE** - User/team preferences (never expires)
- **EPISODIC** - Personal experiences and events (30 days)
- **WORKING** - Current tasks and immediate focus (1 day)
- **SENSORY** - Sensory observations and descriptions (6 hours)

### Cognitive Classification

KuzuMemory automatically classifies memories into cognitive types based on content patterns, providing intuitive categorization that mirrors human memory systems. This standardized model ensures compatibility across Python and TypeScript implementations.

### Pattern-Based Extraction

No LLM required! KuzuMemory uses regex patterns to identify and store memories automatically:

```python
# Automatically detected patterns
"Remember that we use Python for backend"     # β†’ EPISODIC memory
"My name is Alice"                            # β†’ SEMANTIC memory
"I prefer dark mode"                          # β†’ PREFERENCE memory
"Always use type hints"                       # β†’ PROCEDURAL memory
"Currently debugging the API"                 # β†’ WORKING memory
"The interface feels slow"                    # β†’ SENSORY memory
```

**Important**: For pattern matching to work effectively, content should include clear subject-verb-object structures. Memories with specific entities, actions, or preferences are extracted more reliably than abstract statements.

## πŸ—οΈ Architecture

```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   Your App      β”‚    β”‚   KuzuMemory     β”‚    β”‚   Kuzu Graph    β”‚
β”‚                 β”‚    β”‚                  β”‚    β”‚   Database      β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚    β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚    β”‚                 β”‚
β”‚ β”‚  Chatbot    │─┼────┼→│attach_memories│─┼────┼→ Query Engine   β”‚
β”‚ β”‚             β”‚ β”‚    β”‚ β”‚              β”‚ β”‚    β”‚                 β”‚
β”‚ β”‚             β”‚ β”‚    β”‚ β”‚generate_     β”‚ β”‚    β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
β”‚ β”‚             │─┼────┼→│memories      │─┼────┼→│ Pattern     β”‚ β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚    β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚    β”‚ β”‚ Extraction  β”‚ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
                                               β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```

## πŸ”§ Configuration

Create `.kuzu_memory/config.yaml`:

```yaml
version: 1.0

storage:
  max_size_mb: 50
  auto_compact: true
  
recall:
  max_memories: 10
  strategies:
    - keyword
    - entity  
    - temporal

patterns:
  custom_identity: "I am (.*?)(?:\\.|$)"
  custom_preference: "I always (.*?)(?:\\.|$)"
```

## πŸ“Š Performance

| Operation | Target | Typical | Verified |
|-----------|--------|---------|----------|
| Memory Recall | <100ms | ~3ms | βœ… |
| Memory Generation | <200ms | ~8ms | βœ… |
| Database Size | <500 bytes/memory | ~300 bytes | βœ… |
| RAM Usage | <50MB | ~25MB | βœ… |
| Async Learning | Smart wait | 5s default | βœ… |

## πŸ§ͺ Testing

### Quick Start

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run benchmarks
pytest tests/ -m benchmark

# Check coverage
pytest --cov=kuzu_memory
```

### MCP Testing & Diagnostics

KuzuMemory includes comprehensive MCP server testing and diagnostic tools:

```bash
# Run MCP test suite (151+ tests)
pytest tests/mcp/ -v

# Run PROJECT-LEVEL diagnostics (checks project files only)
kuzu-memory doctor

# Quick health check
kuzu-memory doctor health

# MCP-specific diagnostics
kuzu-memory doctor mcp

# Test database connection
kuzu-memory doctor connection

# Performance benchmarks
pytest tests/mcp/performance/ --benchmark-only
```

**Test Coverage**:
- **Unit Tests** (51+ tests) - Protocol and component validation
- **Integration Tests** - Multi-step operations and workflows
- **E2E Tests** - Complete user scenarios
- **Performance Tests** (78 tests) - Latency, throughput, memory profiling
- **Compliance Tests** (73 tests) - JSON-RPC 2.0 and MCP protocol

**Diagnostic Tools** (Project-Level Only):
- Configuration validation with auto-fix
- Connection testing with latency monitoring
- Tool validation and execution testing
- Continuous health monitoring
- Performance regression detection

**Note**: The `doctor` command checks PROJECT-LEVEL configurations only:
- βœ… Project memory database (kuzu-memory/)
- βœ… Claude Code MCP config (.claude/config.local.json)
- βœ… Claude Code hooks (if configured)
- ❌ Does NOT check Claude Desktop (use `kuzu-memory install add claude-desktop` instead)

See [MCP Testing Guide](docs/MCP_TESTING_GUIDE.md) and [MCP Diagnostics Reference](docs/MCP_DIAGNOSTICS.md) for complete documentation.

## 🀝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
git clone https://github.com/kuzu-memory/kuzu-memory
cd kuzu-memory
pip install -e ".[dev]"
pre-commit install
```

## πŸ“„ License

MIT License - see [LICENSE](LICENSE) file for details.

## πŸ”— Links

- [Documentation](https://kuzu-memory.readthedocs.io)
- [PyPI Package](https://pypi.org/project/kuzu-memory/)
- [GitHub Repository](https://github.com/kuzu-memory/kuzu-memory)
- [Issue Tracker](https://github.com/kuzu-memory/kuzu-memory/issues)

## πŸ™ Acknowledgments

- [Kuzu Database](https://kuzudb.com/) - High-performance graph database
- [Pydantic](https://pydantic.dev/) - Data validation library
- [Click](https://click.palletsprojects.com/) - CLI framework

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "kuzu-memory",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "ai, memory, graph, database, kuzu, chatbot, llm",
    "author": null,
    "author_email": "KuzuMemory Team <team@kuzu-memory.dev>",
    "download_url": "https://files.pythonhosted.org/packages/7e/45/ed29f246174f940abb49ae6b2a51fb3e20341786c7bb7f13f3951af9f323/kuzu_memory-1.2.3.tar.gz",
    "platform": null,
    "description": "# KuzuMemory\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://github.com/kuzu-memory/kuzu-memory/workflows/Tests/badge.svg)](https://github.com/kuzu-memory/kuzu-memory/actions)\n\n**Lightweight, embedded graph-based memory system for AI applications**\n\nKuzuMemory provides fast, offline memory capabilities for chatbots and AI systems without requiring LLM calls. It uses pattern matching and local graph storage to remember and recall contextual information.\n\n## \u2728 Key Features\n\n- **\ud83e\udde0 Cognitive Memory Model** - Based on human memory psychology (SEMANTIC, PROCEDURAL, EPISODIC, etc.)\n- **\ud83d\ude80 No LLM Dependencies** - Operates using pattern matching and local NER only\n- **\u26a1 Fast Performance** - <3ms memory recall, <8ms memory generation (verified with Kuzu)\n- **\ud83d\udcbe Embedded Database** - Single-file Kuzu graph database\n- **\ud83d\udd04 Git-Friendly** - Database files <10MB, perfect for version control\n- **\ud83d\udd0c Simple API** - Just two methods: `attach_memories()` and `generate_memories()`\n- **\ud83c\udf10 Cross-Platform** - Standardized cognitive types shared with TypeScript implementation\n- **\ud83d\udcf1 Offline First** - Works completely without internet connection\n- **\ud83d\udd27 MCP Ready** - Native Claude Desktop integration with async learning support\n- **\ud83e\udd16 Hook Compatible** - Ready for claude-mpm hook integration\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Install via pipx (recommended for CLI usage)\npipx install kuzu-memory\n\n# Or install via pip\npip install kuzu-memory\n\n# For development\npip install kuzu-memory[dev]\n```\n\n**Now available on PyPI!** KuzuMemory v1.1.0 is published and ready for production use.\n\n### AI Integration\n\nKuzuMemory can be integrated with various AI systems following the **ONE PATH** principle:\n\n```bash\n# List available integrations\nkuzu-memory install list\n\n# Install Claude Code integration (project-specific memory)\nkuzu-memory install add claude-code\n\n# Install Claude Desktop integration (global memory)\nkuzu-memory install add claude-desktop\n\n# Install Auggie integration\nkuzu-memory install add auggie\n\n# Install universal integration files\nkuzu-memory install add universal\n\n# Check installation status\nkuzu-memory install status\n```\n\n**Primary Installers** (ONE path for each AI system):\n- `claude-code` - Claude Code IDE integration (project-specific memory isolation)\n- `claude-desktop` - Claude Desktop app (global memory across all conversations)\n- `auggie` - Auggie AI integration\n- `universal` - Universal integration files\n\n**Key Differences**:\n\n**Claude Code** (`claude-code`):\n- **Configuration**: Creates `.kuzu-memory/config.yaml` in project directory\n- **Database**: Initializes project database in `.kuzu-memory/memorydb/`\n- **Memory Scope**: Each project has isolated memory\n- **Use Case**: Project-specific context and memories\n- **Sharing**: Memory can be committed to git for team collaboration\n\n**Claude Desktop** (`claude-desktop`):\n- **Configuration**: Creates `~/.kuzu-memory/config.yaml` in home directory\n- **Database**: Initializes global database in `~/.kuzu-memory/memorydb/`\n- **Memory Scope**: Shared across all Claude Desktop conversations\n- **Use Case**: Personal knowledge base and preferences\n- **Installation**: Auto-detects pipx or home directory installation\n\n**Installation Options:**\n- `--force` - Force reinstall even if already installed (overwrites existing config)\n- `--dry-run` - Preview changes without modifying files\n- `--verbose` - Show detailed installation steps\n- `--mode [auto|pipx|home]` - Override auto-detection (claude-desktop only)\n- `--backup-dir PATH` - Custom backup directory\n- `--memory-db PATH` - Custom memory database location\n\n**Automatic Initialization**:\n- Configuration files are created automatically during installation\n- Database is initialized automatically\n- Existing configurations are preserved (use `--force` to overwrite)\n- Backups are created when overwriting existing files\n\nSee [Claude Setup Guide](docs/CLAUDE_SETUP.md) for detailed instructions on Claude Desktop and Claude Code integration.\n\n> **Note**: Previous installer names (e.g., `claude-desktop-pipx`, `claude-desktop-home`) still work but show deprecation warnings.\n\n### Basic Usage\n\n```python\nfrom kuzu_memory import KuzuMemory\n\n# Initialize memory system\nmemory = KuzuMemory()\n\n# Store memories from conversation\nmemory.generate_memories(\"\"\"\nUser: My name is Alice and I work at TechCorp as a Python developer.\nAssistant: Nice to meet you, Alice! Python is a great choice for development.\n\"\"\")\n\n# Retrieve relevant memories\ncontext = memory.attach_memories(\"What's my name and where do I work?\")\n\nprint(context.enhanced_prompt)\n# Output includes: \"Alice\", \"TechCorp\", \"Python developer\"\n```\n\n### CLI Usage\n\n```bash\n# Initialize memory database\nkuzu-memory init\n\n# Store a memory\nkuzu-memory memory store \"I prefer using TypeScript for frontend projects\"\n\n# Recall memories\nkuzu-memory memory recall \"What do I prefer for frontend?\"\n\n# Enhance a prompt\nkuzu-memory memory enhance \"What's my coding preference?\"\n\n# View statistics\nkuzu-memory status\n```\n\n## \ud83d\udcd6 Core Concepts\n\n### Cognitive Memory Types\n\nKuzuMemory uses a cognitive memory model inspired by human memory systems:\n\n- **SEMANTIC** - Facts and general knowledge (never expires)\n- **PROCEDURAL** - Instructions and how-to content (never expires)\n- **PREFERENCE** - User/team preferences (never expires)\n- **EPISODIC** - Personal experiences and events (30 days)\n- **WORKING** - Current tasks and immediate focus (1 day)\n- **SENSORY** - Sensory observations and descriptions (6 hours)\n\n### Cognitive Classification\n\nKuzuMemory automatically classifies memories into cognitive types based on content patterns, providing intuitive categorization that mirrors human memory systems. This standardized model ensures compatibility across Python and TypeScript implementations.\n\n### Pattern-Based Extraction\n\nNo LLM required! KuzuMemory uses regex patterns to identify and store memories automatically:\n\n```python\n# Automatically detected patterns\n\"Remember that we use Python for backend\"     # \u2192 EPISODIC memory\n\"My name is Alice\"                            # \u2192 SEMANTIC memory\n\"I prefer dark mode\"                          # \u2192 PREFERENCE memory\n\"Always use type hints\"                       # \u2192 PROCEDURAL memory\n\"Currently debugging the API\"                 # \u2192 WORKING memory\n\"The interface feels slow\"                    # \u2192 SENSORY memory\n```\n\n**Important**: For pattern matching to work effectively, content should include clear subject-verb-object structures. Memories with specific entities, actions, or preferences are extracted more reliably than abstract statements.\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510    \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   Your App      \u2502    \u2502   KuzuMemory     \u2502    \u2502   Kuzu Graph    \u2502\n\u2502                 \u2502    \u2502                  \u2502    \u2502   Database      \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502    \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502    \u2502                 \u2502\n\u2502 \u2502  Chatbot    \u2502\u2500\u253c\u2500\u2500\u2500\u2500\u253c\u2192\u2502attach_memories\u2502\u2500\u253c\u2500\u2500\u2500\u2500\u253c\u2192 Query Engine   \u2502\n\u2502 \u2502             \u2502 \u2502    \u2502 \u2502              \u2502 \u2502    \u2502                 \u2502\n\u2502 \u2502             \u2502 \u2502    \u2502 \u2502generate_     \u2502 \u2502    \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502             \u2502\u2500\u253c\u2500\u2500\u2500\u2500\u253c\u2192\u2502memories      \u2502\u2500\u253c\u2500\u2500\u2500\u2500\u253c\u2192\u2502 Pattern     \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502    \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502    \u2502 \u2502 Extraction  \u2502 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    \u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n                                               \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## \ud83d\udd27 Configuration\n\nCreate `.kuzu_memory/config.yaml`:\n\n```yaml\nversion: 1.0\n\nstorage:\n  max_size_mb: 50\n  auto_compact: true\n  \nrecall:\n  max_memories: 10\n  strategies:\n    - keyword\n    - entity  \n    - temporal\n\npatterns:\n  custom_identity: \"I am (.*?)(?:\\\\.|$)\"\n  custom_preference: \"I always (.*?)(?:\\\\.|$)\"\n```\n\n## \ud83d\udcca Performance\n\n| Operation | Target | Typical | Verified |\n|-----------|--------|---------|----------|\n| Memory Recall | <100ms | ~3ms | \u2705 |\n| Memory Generation | <200ms | ~8ms | \u2705 |\n| Database Size | <500 bytes/memory | ~300 bytes | \u2705 |\n| RAM Usage | <50MB | ~25MB | \u2705 |\n| Async Learning | Smart wait | 5s default | \u2705 |\n\n## \ud83e\uddea Testing\n\n### Quick Start\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run all tests\npytest\n\n# Run benchmarks\npytest tests/ -m benchmark\n\n# Check coverage\npytest --cov=kuzu_memory\n```\n\n### MCP Testing & Diagnostics\n\nKuzuMemory includes comprehensive MCP server testing and diagnostic tools:\n\n```bash\n# Run MCP test suite (151+ tests)\npytest tests/mcp/ -v\n\n# Run PROJECT-LEVEL diagnostics (checks project files only)\nkuzu-memory doctor\n\n# Quick health check\nkuzu-memory doctor health\n\n# MCP-specific diagnostics\nkuzu-memory doctor mcp\n\n# Test database connection\nkuzu-memory doctor connection\n\n# Performance benchmarks\npytest tests/mcp/performance/ --benchmark-only\n```\n\n**Test Coverage**:\n- **Unit Tests** (51+ tests) - Protocol and component validation\n- **Integration Tests** - Multi-step operations and workflows\n- **E2E Tests** - Complete user scenarios\n- **Performance Tests** (78 tests) - Latency, throughput, memory profiling\n- **Compliance Tests** (73 tests) - JSON-RPC 2.0 and MCP protocol\n\n**Diagnostic Tools** (Project-Level Only):\n- Configuration validation with auto-fix\n- Connection testing with latency monitoring\n- Tool validation and execution testing\n- Continuous health monitoring\n- Performance regression detection\n\n**Note**: The `doctor` command checks PROJECT-LEVEL configurations only:\n- \u2705 Project memory database (kuzu-memory/)\n- \u2705 Claude Code MCP config (.claude/config.local.json)\n- \u2705 Claude Code hooks (if configured)\n- \u274c Does NOT check Claude Desktop (use `kuzu-memory install add claude-desktop` instead)\n\nSee [MCP Testing Guide](docs/MCP_TESTING_GUIDE.md) and [MCP Diagnostics Reference](docs/MCP_DIAGNOSTICS.md) for complete documentation.\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/kuzu-memory/kuzu-memory\ncd kuzu-memory\npip install -e \".[dev]\"\npre-commit install\n```\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd17 Links\n\n- [Documentation](https://kuzu-memory.readthedocs.io)\n- [PyPI Package](https://pypi.org/project/kuzu-memory/)\n- [GitHub Repository](https://github.com/kuzu-memory/kuzu-memory)\n- [Issue Tracker](https://github.com/kuzu-memory/kuzu-memory/issues)\n\n## \ud83d\ude4f Acknowledgments\n\n- [Kuzu Database](https://kuzudb.com/) - High-performance graph database\n- [Pydantic](https://pydantic.dev/) - Data validation library\n- [Click](https://click.palletsprojects.com/) - CLI framework\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Lightweight, embedded graph-based memory system for AI applications",
    "version": "1.2.3",
    "project_urls": {
        "Documentation": "https://kuzu-memory.readthedocs.io",
        "Homepage": "https://github.com/kuzu-memory/kuzu-memory",
        "Issues": "https://github.com/kuzu-memory/kuzu-memory/issues",
        "Repository": "https://github.com/kuzu-memory/kuzu-memory"
    },
    "split_keywords": [
        "ai",
        " memory",
        " graph",
        " database",
        " kuzu",
        " chatbot",
        " llm"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5d44d9ab1ea34ca41ab15948a2fe56872a53a393d5db10d0969a03a14637b3a5",
                "md5": "a7f0d19c192a54ab908a01245237085d",
                "sha256": "69390cc25460bb1fb6127d399c58fbebcb1af19c6573054ad2054458a43d6b61"
            },
            "downloads": -1,
            "filename": "kuzu_memory-1.2.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "a7f0d19c192a54ab908a01245237085d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 376321,
            "upload_time": "2025-10-06T21:25:18",
            "upload_time_iso_8601": "2025-10-06T21:25:18.480699Z",
            "url": "https://files.pythonhosted.org/packages/5d/44/d9ab1ea34ca41ab15948a2fe56872a53a393d5db10d0969a03a14637b3a5/kuzu_memory-1.2.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "7e45ed29f246174f940abb49ae6b2a51fb3e20341786c7bb7f13f3951af9f323",
                "md5": "cf7553adbaaba68b7865ca510a0e62e3",
                "sha256": "f0d722b936ece50b16e2955c827559f07c6127adbffc9d81882a7757691e2d2a"
            },
            "downloads": -1,
            "filename": "kuzu_memory-1.2.3.tar.gz",
            "has_sig": false,
            "md5_digest": "cf7553adbaaba68b7865ca510a0e62e3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 340257,
            "upload_time": "2025-10-06T21:25:23",
            "upload_time_iso_8601": "2025-10-06T21:25:23.770414Z",
            "url": "https://files.pythonhosted.org/packages/7e/45/ed29f246174f940abb49ae6b2a51fb3e20341786c7bb7f13f3951af9f323/kuzu_memory-1.2.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-06 21:25:23",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "kuzu-memory",
    "github_project": "kuzu-memory",
    "github_not_found": true,
    "lcname": "kuzu-memory"
}
        
Elapsed time: 1.44572s