long-term-memory 0.3.0__tar.gz

long_term_memory-0.3.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# AIMemory runtime data
+memory_db/
+checkpoints/
+
+# Data artifacts (keep raw source files, ignore generated)
+data/embeddings/
+data/plots/
+data/splits/
+
+# Claude Code
+.claude/plans/

long_term_memory-0.3.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-03-01
+
+### Changed
+
+- **Project renamed** from `mcp-memory-server` to `long-term-memory`. Python import name (`aimemory`) and CLI commands unchanged.
+- **GitHub repository** renamed to `long-term-memory` (old URL auto-redirects)
+
+### Added
+
+- **Auto-linking** — New memories automatically link to similar existing ones (similarity ≥ 0.92) via bidirectional graph edges
+- **Live graph visualization** (`aimemory-live`) — Real-time WebSocket-based memory graph in the browser
+  - Force-directed layout (vis.js ForceAtlas2) with category-based coloring
+  - Glow effects on save (green) and search (blue)
+  - Event log sidebar with hover-to-highlight related nodes
+  - Persistent event history across browser refreshes
+  - Cross-process event push (MCP → live server via WebSocket `/event` path)
+- **`memory_visualize` tool** — Generate interactive static HTML graph (13th MCP tool)
+- **`[live]` optional dependency** — `websockets>=12.0`
+
+### Deprecated
+
+- PyPI package `mcp-memory-server` — use `long-term-memory` instead
+
+## [0.2.0] - 2026-02-28
+
+First public release.
+
+### Added
+
+- **MCP Server** with 12 tools: `auto_search`, `memory_save`, `memory_search`, `memory_update`, `memory_delete`, `memory_get_related`, `memory_pin`, `memory_unpin`, `memory_stats`, `sleep_cycle_run`, `policy_status`, `policy_decide`
+- **RL Memory Policy** — Rule-based importance scoring + MLP contextual bandit (SAVE/SKIP/RETRIEVE)
+- **Enhanced Policy** (opt-in) — 778d state encoder (SentenceTransformer 768d + 10d hand-crafted), experience replay buffer, progressive autonomy
+- **Semantic Search** — ChromaDB vector store with `intfloat/multilingual-e5-small` embeddings
+- **Knowledge Graph** — NetworkX-based entity-relation graph with multi-hop traversal
+- **GraphRAG Hybrid Retrieval** (opt-in) — Vector similarity + graph traversal with RL re-ranker (11d features)
+- **Multi-Resolution Text** — 3 levels (full text, keyword summary, entity triples) with token-budget-aware composition
+- **Forgetting Pipeline** — Decay-based aging with compress → deactivate → delete stages
+- **Sleep Cycle** — Periodic maintenance: consolidation, resolution regeneration, forgetting, checkpoint saving
+- **Immutable Memories** — Protected from modification/deletion with SHA-256 rule hash verification
+- **Pin/Unpin** — User-controlled forgetting protection
+- **Multilingual Support** — Korean (ko) and English (en) i18n patterns
+- **P2P Federated Learning** — Gossip protocol with differential privacy and Krum aggregation
+- **A/B Comparison Framework** — Baseline vs re-ranked retrieval comparison
+- **CI/CD** — GitHub Actions with Python 3.11/3.12/3.13 matrix
+- **611 tests** passing across 31 test files
+
+### Removed
+
+- Deprecated DualHeadDQN offline training pipeline (replaced by online MLP bandit)
+- `ExtractorConfig` (unused after DQN removal)

long_term_memory-0.3.0/CLAUDE.md

@@ -0,0 +1,12 @@
+# Long-Term Memory System
+
+## Overview
+Persistent, self-organizing long-term memory for AI assistants. MCP server with semantic search, knowledge graphs, RL-powered retrieval, and real-time graph visualization.
+
+- PyPI package: `long-term-memory` (previously `mcp-memory-server`)
+- Python import: `aimemory` (unchanged)
+- CLI: `aimemory-mcp`, `aimemory-viz`, `aimemory-live`
+
+## Conventions
+- Use the `.claude/agents/` directory for custom agent definitions
+- Agents are defined as markdown files describing their role, tools, and instructions

long_term_memory-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIMemory Contributors
+
+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.

long_term_memory-0.3.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: long-term-memory
+Version: 0.3.0
+Summary: Long-term memory system for AI assistants — persistent, searchable, self-organizing memory powered by semantic search, knowledge graphs, and reinforcement learning
+Project-URL: Homepage, https://github.com/ihwooMil/long-term-memory
+Project-URL: Repository, https://github.com/ihwooMil/long-term-memory
+Project-URL: Issues, https://github.com/ihwooMil/long-term-memory/issues
+Project-URL: Changelog, https://github.com/ihwooMil/long-term-memory/blob/main/CHANGELOG.md
+Author: ihwoo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,knowledge-graph,llm,long-term-memory,mcp,memory,rag,reinforcement-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.14,>=3.11
+Requires-Dist: chromadb>=0.5.0
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sentence-transformers>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: ko
+Requires-Dist: mecab-ko-dic>=1.0.0; extra == 'ko'
+Requires-Dist: mecab-python3>=1.0.9; extra == 'ko'
+Provides-Extra: live
+Requires-Dist: websockets>=12.0; extra == 'live'
+Provides-Extra: train
+Requires-Dist: matplotlib>=3.8; extra == 'train'
+Requires-Dist: ollama>=0.4.0; extra == 'train'
+Requires-Dist: pandas>=2.0; extra == 'train'
+Requires-Dist: pyarrow>=15.0; extra == 'train'
+Requires-Dist: tqdm>=4.66; extra == 'train'
+Provides-Extra: viz
+Requires-Dist: pyvis>=0.3.2; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# Long-Term Memory
+
+**Persistent, self-organizing memory for AI assistants.**
+
+> Drop-in MCP server that gives Claude (and any MCP client) long-term memory — powered by semantic search, knowledge graphs, and reinforcement learning.
+
+[![CI](https://github.com/ihwooMil/long-term-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/ihwooMil/long-term-memory/actions)
+[![PyPI](https://img.shields.io/pypi/v/long-term-memory)](https://pypi.org/project/long-term-memory/)
+[![Python](https://img.shields.io/pypi/pyversions/long-term-memory)](https://pypi.org/project/long-term-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **Note:** This package was previously published as [`mcp-memory-server`](https://pypi.org/project/mcp-memory-server/). That package is deprecated — please use `long-term-memory` going forward.
+
+---
+
+## Why Long-Term Memory?
+
+Current AI memory tools have two critical problems:
+
+| Problem | How we solve it |
+|---------|----------------|
+| **Manual retrieval** — you must ask "do you remember X?" | `auto_search` runs every turn, injecting relevant memories automatically |
+| **Token waste** — entire memory dump inserted into context | Multi-resolution composer selects top-K memories within a token budget |
+
+## Key Features
+
+- **RL-powered policy** — Contextual bandit decides when to save, skip, or retrieve (not just keyword matching)
+- **Semantic search** — ChromaDB + multilingual sentence-transformer embeddings (`intfloat/multilingual-e5-small`)
+- **Knowledge graph** — Entity-relation graph (NetworkX) for multi-hop reasoning
+- **GraphRAG hybrid retrieval** — Vector similarity + graph traversal, fused and re-ranked by an RL re-ranker
+- **Auto-linking** — New memories automatically link to similar existing ones (similarity ≥ 0.92)
+- **Multi-resolution text** — Full text → summary → entity triples, composed within token budget
+- **Forgetting pipeline** — Decay-based aging with consolidation, pinning, and immutable protection
+- **Sleep cycle** — Periodic maintenance: dedup, compress, forget, checkpoint
+- **Live graph** — Real-time WebSocket visualization of the memory graph
+- **Multilingual** — Korean and English pattern support out of the box
+
+---
+
+## Quick Start (2 minutes)
+
+### 1. Install
+
+```bash
+pip install long-term-memory
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install long-term-memory
+```
+
+<details>
+<summary>Optional extras</summary>
+
+```bash
+pip install long-term-memory[ko]     # Korean NLP support
+pip install long-term-memory[live]   # Real-time graph visualization
+pip install long-term-memory[viz]    # Static graph visualization
+```
+</details>
+
+### 2. Connect to OpenClaw
+
+```bash
+mcporter config add aimemory --command aimemory-mcp --scope home
+```
+
+### 3. Connect to Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "aimemory": {
+      "command": "aimemory-mcp"
+    }
+  }
+}
+```
+
+That's it. Claude now has persistent memory across all conversations.
+
+<details>
+<summary>With live graph visualization</summary>
+
+```json
+{
+  "mcpServers": {
+    "aimemory": {
+      "command": "aimemory-mcp",
+      "args": ["--with-live"]
+    }
+  }
+}
+```
+
+Then open `http://127.0.0.1:8765` to see the live memory graph.
+</details>
+
+<details>
+<summary>Advanced: custom data path or uv project mode</summary>
+
+```json
+{
+  "mcpServers": {
+    "aimemory": {
+      "command": "uv",
+      "args": ["run", "--project", "/path/to/long-term-memory", "aimemory-mcp", "--with-live"],
+      "env": {
+        "AIMEMORY_DB_PATH": "/path/to/memory_db"
+      }
+    }
+  }
+}
+```
+</details>
+
+### 4. Connect to Claude Code
+
+```bash
+claude mcp add aimemory -- aimemory-mcp
+```
+
+Or with live graph:
+
+```bash
+claude mcp add aimemory -- aimemory-mcp --with-live
+```
+
+---
+
+## Live Graph Visualization
+
+Real-time WebSocket-based memory graph that updates as memories are saved, searched, or deleted.
+
+```bash
+# Option 1: auto-start with MCP server
+aimemory-mcp --with-live
+
+# Option 2: standalone server
+aimemory-live --port 8765
+
+# Option 3: via environment variable
+AIMEMORY_LIVE=1 aimemory-mcp
+```
+
+Open `http://127.0.0.1:8765` in a browser. Requires the `[live]` extra (`pip install long-term-memory[live]`). Features:
+
+- Force-directed graph layout with category-based coloring
+- New nodes glow green on save, blue on search
+- Event log sidebar with hover-to-highlight (hover a log entry to highlight related nodes)
+- Persistent event history across browser refreshes
+- Cross-process events — MCP server pushes events to the live graph via WebSocket
+
+---
+
+## MCP Tools (13)
+
+| Tool | Description |
+|------|-------------|
+| `auto_search` | Auto-retrieve relevant memories at turn start (multi-resolution context) |
+| `memory_save` | Save a new memory with keywords, category, and relations |
+| `memory_search` | Semantic similarity search |
+| `memory_update` | Update content or keywords of an existing memory |
+| `memory_delete` | Delete a memory (respects immutability) |
+| `memory_get_related` | BFS graph traversal for related memories |
+| `memory_pin` / `memory_unpin` | Protect memories from forgetting |
+| `memory_stats` | Total count and category breakdown |
+| `memory_visualize` | Generate interactive graph HTML |
+| `sleep_cycle_run` | Trigger maintenance (consolidation + forgetting + checkpoint) |
+| `policy_status` | RL policy state (epsilon, action distribution, updates) |
+| `policy_decide` | Ask the RL policy for a SAVE/SKIP/RETRIEVE decision with reasoning |
+
+---
+
+## Configuration
+
+All settings via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AIMEMORY_DB_PATH` | `./memory_db` | ChromaDB persistence directory |
+| `AIMEMORY_LANGUAGE` | `ko` | Language for pattern matching (`ko` / `en`) |
+| `AIMEMORY_EMBEDDING_MODEL` | `intfloat/multilingual-e5-small` | Sentence-transformer model |
+| `AIMEMORY_LOG_LEVEL` | `INFO` | Logging level |
+| `AIMEMORY_ENHANCED_POLICY` | `0` | Enable 778d enhanced RL policy (`1` to enable) |
+| `AIMEMORY_GRAPH_RAG` | `0` | Enable GraphRAG hybrid retrieval (`1` to enable) |
+| `AIMEMORY_LIVE_HOST` | `127.0.0.1` | Live graph server host (for event push) |
+| `AIMEMORY_LIVE_PORT` | `8765` | Live graph server port (for event push) |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                   MCP Client                     │
+│          (Claude Desktop / Claude Code)          │
+└────────────────────┬────────────────────────────┘
+                     │ stdio (JSON-RPC)
+┌────────────────────▼────────────────────────────┐
+│              FastMCP Server (13 tools)           │
+├──────────────────────────────────────────────────┤
+│              MemoryBridge (orchestrator)          │
+├──────────┬──────────┬──────────┬─────────────────┤
+│ RL Policy│ Retrieval│ Storage  │ Maintenance      │
+│          │          │          │                  │
+│ Rule-    │ ChromaDB │ Graph    │ Sleep Cycle      │
+│ Based +  │ vector + │ Memory   │ (consolidation,  │
+│ MLP      │ Knowledge│ Store    │  forgetting,     │
+│ Bandit   │ Graph    │          │  checkpoints)    │
+│          │ (GraphRAG)│         │                  │
+│ Re-ranker│          │          │                  │
+│ (11d MLP)│          │          │                  │
+└──────────┴──────────┴──────────┴─────────────────┘
+         ↕ WebSocket (cross-process)
+┌──────────────────────────────────────────────────┐
+│          Live Graph Server (aimemory-live)        │
+│     vis.js force-directed graph + event log      │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/ihwooMil/long-term-memory.git
+cd long-term-memory
+uv sync --extra dev
+
+# Run tests (611+ tests)
+uv run pytest tests/ -q
+
+# Lint & format
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+```
+
+---
+
+## Migrating from mcp-memory-server
+
+```bash
+pip uninstall mcp-memory-server
+pip install long-term-memory
+```
+
+No code changes needed — the Python import name (`aimemory`) and CLI commands (`aimemory-mcp`, `aimemory-viz`, `aimemory-live`) remain the same.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.