Metadata-Version: 2.4
Name: falkordb-memory-server
Version: 0.2.0
Summary: Cross-platform, cross-agent memory system using FalkorDB graph database
Author: OMC Team
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: falkordb>=1.6.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy<2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: torch>=2.2.2
Requires-Dist: uvicorn>=0.22.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# FalkorDB Memory

### The Graph-Native Memory System for Software Development

<br>

*"Why did we choose PostgreSQL?" "Have we seen this bug before?" "What's the pattern for this API?"*

Every developer knows these questions. The answers live in past conversations — buried in chat history, lost between sessions, scattered across tools. **FalkorDB Memory gives your AI agents a persistent brain** that remembers decisions, traces code patterns, and connects knowledge across projects.

**One graph database** — FalkorDB combines vector search + graph relationships in a single Redis-based store. No separate ChromaDB + SQLite. No context fragmentation.

**Native graph queries** — Trace decision chains, find problem patterns, discover hidden connections with Cypher: `MATCH (d:Decision)-[:LED_TO]->(p:Problem) RETURN d.rationale, p.solution`

**Zero-cost extraction** — Pure regex matching, no API calls, 96.6% benchmark accuracy. Decisions, bugs, learnings, patterns — auto-classified and stored.

<br>

[![][python-shield]][python-link]
[![][license-shield]][license-link]
[![][falkordb-shield]][falkordb-link]

<br>

[Quick Start](#quick-start) · [Features](#features) · [Why Graph?](#why-graph-native) · [MCP Tools](#mcp-tools) · [Roadmap](#roadmap)

<br>

### One graph. Zero fragmentation. Native connections.

<table>
<tr>
<td align="center"><strong>15+</strong><br><sub>MCP Tools</sub></td>
<td align="center"><strong>Graph+Vector</strong><br><sub>One Database</sub></td>
<td align="center"><strong>$0</strong><br><sub>Extraction Cost</sub></td>
<td align="center"><strong>Cypher</strong><br><sub>Native Queries</sub></td>
</tr>
</table>

**vs Alternatives**

| Feature | FalkorDB Memory | MemPalace | claude-mem |
|---------|-----------------|-----------|------------|
| Storage | **One graph DB** | ChromaDB + SQLite | SQLite + ChromaDB |
| Graph queries | **Native Cypher** | Simulated | None |
| Vector search | **Built-in** | ChromaDB | ChromaDB |
| Relationship traversal | **Native edges** | Logic layer | None |

</div>

---

## Quick Start

```bash
# Install dependencies
pip install falkordb-memory-server

# Unified Interactive Installer
# (Auto-configures Claude Code, Gemini CLI, OpenClaw, and FalkorDB Docker)
python -m falkordb_memory_server install
```

After installation, your AI agents automatically:
- **Capture memories** from conversations and tool usage
- **Inject context** from relevant past memories at session start
- **Search semantically** across all stored knowledge

---

## Features

### 🧠 Memory Extraction

Automatic classification of memories into 7 categories:

| Category | Description | Example Patterns |
|----------|-------------|------------------|
| `decision` | Choices made, trade-offs | "We decided to...", "instead of" |
| `preference` | Coding style, conventions | "I always use...", "never do" |
| `milestone` | Achievements, breakthroughs | "It worked!", "fixed", "solved" |
| `problem` | Bugs, issues, failures | "error", "crash", "bug" |
| `learning` | Insights, patterns, tips | "learned", "insight", "tip" |
| `emotional` | Feelings, reactions | "love", "proud", "frustrated" |
| `general` | Default category | - |

**Extraction Modes**
Optimize extraction rules based on your context:
- **Programming (Default)**: Best for software architecture, code snippets & technical decisions.
- **Office**: Best for scheduling, meeting summaries, emails & daily tasks. Automatically redacts Phone numbers, ID cards, and Bank cards.
- **Life**: Best for personal reminders, home tasks & finances.

**Zero API calls** — Pure regex pattern matching achieves 96.6% LongMemEval accuracy (MemPalace benchmark).

### 🔗 Graph Storage

Memories are nodes. Relationships are edges. Discover connections:

```cypher
// Find all decisions that led to problems
MATCH (d:Decision)-[:LED_TO]->(p:Problem)
RETURN d.rationale, p.solution

// Find related learnings
MATCH (l:Learning)-[:DERIVED_FROM]->(c:Code)
WHERE l.category = 'security'
RETURN l, c
```

### 🔍 Semantic Search

Vector similarity search powered by sentence-transformers:

```python
# Find similar memories
results = memory_semantic_search(
    query="authentication best practices",
    k=10,
    min_score=0.7
)
```

### 💡 Proactive Insights

**Shift from Passive Recall to Active Context Streaming** — The system intercepts tool usage or user prompts and proactively pushes relevant historical architecture decisions to your agent's context window.

- **Turn-Driven Injection**: Searches the graph for conventions related to the currently requested files or topics.
- **Async State Rendering**: Automatically updates localized workspace files (`.omg/state/active-architecture.md`) to align the agent's system prompt without blocking execution.
- **Zero Context Pollution**: Protects token limits with strict 1-hour session deduplication and confidence-based truncation.

### 🛡️ Privacy & Security Guardrails

**Built-in PII and Secrets Redaction (`PIIRedactor`)** ensures that sensitive data never leaks into the graph database.

- **Automated Secrets Filtering**: Detects and replaces AWS Keys, JWT tokens, private keys, and passwords with `[REDACTED_SECRET]`.
- **PII Scrubbing**: Automatically removes email addresses and public IP addresses.
- **Developer-Friendly Bypasses**: Safely ignores common dummy passwords (like `test`, `dummy`) and standard local network IPs (`127.0.0.1`, `192.168.x.x`) to prevent blocking legitimate local development.

### 🪝 Cross-Agent Hooks

| Agent | Hook Events | Config |
|-------|-------------|--------|
| Claude Code | `PreToolUse`, `PostToolUse` | `~/.claude/settings.json` |
| Gemini CLI | `BeforeTool`, `AfterTool`, `SessionStart` | `gemini-extension.json` |

Unified event mapping:

```
Claude Code          Gemini CLI           Unified
───────────────────────────────────────────────────
PreToolUse      →   BeforeTool      →   before_tool
PostToolUse     →   AfterTool       →   after_tool
-               →   SessionStart    →   session_start
```

---

## Installation

### Prerequisites

1. **FalkorDB** (Redis-based graph database):
   ```bash
   docker run -d -p 6379:6379 --name falkordb falkordb/falkordb:latest
   ```

2. **Python 3.10+**

### Option 1: Install from PyPI

```bash
# Using pipx (recommended)
pipx install falkordb-memory-server

# Or using uv
uv tool install falkordb-memory-server

# Or standard pip
pip install falkordb-memory-server
```

### Option 2: Install from Source (Development)

```bash
git clone https://github.com/goodideal/falkordb-memory.git
cd falkordb-memory
pip install -e .
```

### Run Unified Installer

After installation, run the built-in installer to automatically configure your AI agents (Claude Code, Gemini CLI, OpenClaw) with the required MCP server and background lifecycle hooks:

```bash
python -m falkordb_memory_server install
```

The interactive wizard will help you:
1. Choose which agents to integrate with (or `all`).
2. Configure your `FALKORDB_URL` (with an option to automatically spin up a local Docker container).
3. Safely back up your current agent configurations and inject the MCP/Hook settings.

*To revert, simply run:*
```bash
python -m falkordb_memory_server uninstall
```

---

## MCP Tools

### Memory Operations

| Tool | Description |
|------|-------------|
| `memory_remember` | Store a new memory |
| `memory_recall` | Search and retrieve memories |
| `memory_associate` | Create relationships between memories |
| `memory_forget` | Delete memories (supports TTL) |

### Extraction Tools

| Tool | Description |
|------|-------------|
| `memory_extract` | Extract memories from text |
| `memory_mine` | Batch mine memories from files/directories |

### Search Tools

| Tool | Description |
|------|-------------|
| `memory_semantic_search` | Vector similarity search |
| `memory_query` | Execute raw Cypher queries |

### Session Management

| Tool | Description |
|------|-------------|
| `memory_start_session` | Begin a new agent session |
| `memory_end_session` | End current session |

### Maintenance

| Tool | Description |
|------|-------------|
| `memory_stats` | View memory statistics |
| `memory_cleanup` | Clean expired memories |

---

## Usage Examples

### Store a Memory

```
"Remember that we decided to use PostgreSQL for the database because it handles JSON better"
```

**Note:** When using `memory_remember` tool directly, `content` and `context` must be **dictionaries**, not strings:

```json
{
  "memory_type": "decision",
  "content": {
    "title": "Database Choice",
    "description": "We chose PostgreSQL",
    "rationale": "Better JSON support"
  },
  "context": {
    "project": "my-project"
  }
}
```

### Recall Memories

```
"What do you remember about authentication?"
"Find decisions we made about the API"
```

### Extract from Files

```
"Mine the docs directory for important decisions"
"Extract learnings from this conversation"
```

### Graph Queries

```
"Show me all problems we've solved"
"What decisions led to this architecture?"
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Agent Layer                              │
│   Claude Code │ Gemini CLI │ Codex │ Custom Agents          │
└─────────────────────┬───────────────────────────────────────┘
                      │ MCP Protocol / Hooks
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              FalkorDB Memory MCP Server                      │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
│  │Graph Tools  │ │Memory Tools │ │ Extraction Tools        ││
│  │- query      │ │- remember   │ │- memory_extract         ││
│  │- create     │ │- recall     │ │- memory_mine            ││
│  │- delete     │ │- associate  │ │                         ││
│  └─────────────┘ └─────────────┘ └─────────────────────────┘│
└─────────────────────┬───────────────────────────────────────┘
                      │ falkordb-py SDK
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    FalkorDB (Redis)                          │
│  Nodes: Session, Agent, Decision, Learning, Code, Concept   │
│  Edges: STARTED_BY, LED_TO, KNOWS, RELATED_TO               │
│  Indexes: Vector (semantic), Full-text (search)             │
└─────────────────────────────────────────────────────────────┘
```

---

## OpenClaw Advanced Configuration

To ensure OpenClaw seamlessly relies on `falkordb-memory` for context management and background extraction, follow these advanced configuration steps:

### 1. Disable Built-in Memory MCP
OpenClaw may ship with a default memory system or other memory MCP servers. To avoid context conflicts, remove or disable any other memory servers in your `~/.openclaw/openclaw.json`. 
Ensure the `mcp.servers` object only contains `falkordb-memory` (alongside your other non-memory plugins).

### 2. Enforce Usage via System Prompt
Update your OpenClaw custom instructions (e.g., `systemPrompt` or `customInstructions` in your configuration) by appending this mandate to enforce exclusive usage of FalkorDB:
```markdown
# Memory Management Mandate
You are connected to a FalkorDB graph memory system.
1. **Disable Local Memory**: Do not use built-in files or default memory banks.
2. **Exclusive Usage**: When persisting preferences, architecture decisions, or lessons learned, you MUST ONLY use the `memory_remember` or `memory_extract` tools.
3. **Recall**: For new tasks or ambiguous context, proactively call `memory_recall` to retrieve historical decisions from the knowledge graph.
```

### 3. Enable Passive Memory Hook (Optional)
To capture memories in the background without requiring the agent to make active tool calls, configure OpenClaw to pipe its session events to our hook script.
If your OpenClaw setup supports lifecycle hooks (e.g., triggering after a model reply or a tool result), add the following to your configuration:
```json
{
  "hooks": {
    "onEvent": {
      "command": "falkordb-memory-openclaw-hook"
    }
  }
}
```
*(Note: OpenClaw will automatically pipe the event JSON payload via STDIN to the script, which `openclaw-hook.py` will then parse and process).*

---

## Configuration

### Environment Variables

```bash
FALKORDB_URL=redis://localhost:6379
GRAPH_NAME=agent_memory
EMBEDDING_MODEL=all-MiniLM-L6-v2
DEFAULT_TTL=604800  # 7 days
```

### Embedding Models

Local embedding models powered by sentence-transformers — **no API key required**.

| Model | Dimensions | Size | Speed | Accuracy |
|-------|------------|------|-------|----------|
| `all-MiniLM-L6-v2` | 384 | ~90MB | Fast | Good |
| `all-mpnet-base-v2` | 768 | ~420MB | Slower | Better |

**How it works:**
- Models are **auto-downloaded** on first use to `~/.cache/torch/sentence_transformers/`
- After initial download, works **completely offline** — no API calls, no network required
- Zero extraction cost — pure pattern matching for memory classification
- Semantic search uses local embeddings for vector similarity

**Install dependencies:**
```bash
pip install sentence-transformers torch
```

**Switch models:**
```bash
# Use higher accuracy model
export EMBEDDING_MODEL=all-mpnet-base-v2
export EMBEDDING_DIMENSION=768
```

---

## Roadmap

### v1.0 (Foundation)

- ✅ MCP server with graph operations
- ✅ FalkorDB integration (Redis graph database)
- ✅ Basic memory tools: remember, recall, forget
- ✅ Node labels: Session, Agent, Decision, Learning, Code, Concept
- ✅ Relationship types: STARTED_BY, LED_TO, DERIVED_FROM, KNOWS

### v1.1 (Current)

- ✅ Memory extraction with rule-based patterns
- ✅ Claude Code and Gemini CLI hooks
- ✅ Semantic search with local embeddings
- ✅ Batch file/directory mining

### v1.2 (Developer Core)

*Solve everyday development pain points*

- ✅ Decision Chain Query — trace architecture decisions (`"Why PostgreSQL?"`)
- ✅ Bug Pattern Registry — remember solved problems (`"Seen this error before?"`)
- ✅ Code Pattern Memory — API usage and patterns (`"React hooks best practices"`)
- ✅ Privacy Control — `<private>` tags to exclude sensitive content
- ✅ Wake-up Command — load project-critical facts into context
- ✅ **Incremental Mining** — track file changes (hash/mtime), skip unchanged files, avoid duplicate storage

### v1.3 (Project Knowledge)

*Project-level context management*

- ✅ Project Context Auto-Load — conventions, configs, dependencies
- ✅ Dependency Decision Memory — why we chose X over Y
- ✅ Convention Registry — coding standards, naming patterns
- ✅ Knowledge Graph — temporal entity relationships with Cypher

### v1.4 (Dev Workflow Integration)

*Integrate into development process*

- ✅ Refactor Trail — track refactoring reasons and impact
- ✅ Test Memory — test strategies, edge cases, coverage decisions
- ✅ API Usage Memory — third-party API experiences
- ✅ Code Review Memory — review feedback and improvements

### v1.5 (Enhanced Experience)

- ✅ Web Viewer UI — graph visualization at `localhost:37777`
- ✅ Endless Mode — biomimetic memory for long sessions (L0-L3 stack)
- ✅ Progressive Disclosure — 3-layer search workflow
- ✅ Conversation Mining — multi-format support (Claude, ChatGPT, Slack)

### v2.0 (Enterprise)

- 🔲 AAAK Dialect — compression for repeated entities at scale
- 🔲 Advanced Graph Analytics — influence analysis, pattern detection, community detection
- 🔲 Multi-tenant Support — isolated memory per team/project
- 🔲 Team Memory Sharing — cross-team knowledge sync

---

## Troubleshooting

### First Run: Model Download

On first use, the embedding model will be downloaded automatically:

```
INFO:falkordb_memory_server.server:Loading embedding model: all-MiniLM-L6-v2
```

This is a **one-time download** (~90MB). After that, it works completely offline.

### Cypher Syntax Notes

FalkorDB uses OpenCypher with some differences:

```cypher
# ❌ Not supported - datetime() function
CREATE (n:Decision {created_at: datetime()})

# ✅ Correct - pass timestamp from Python
CREATE (n:Decision {created_at: "2024-01-15T10:30:00"})
```

### MCP Server Not Connecting

1. Verify FalkorDB is running:
   ```bash
   docker ps | grep falkordb
   ```

2. Check MCP server status:
   ```bash
   claude mcp list
   ```

3. Restart the MCP server:
   ```bash
   claude mcp remove falkordb-memory
   claude mcp add falkordb-memory -e FALKORDB_URL=redis://localhost:6379 -- python -m falkordb_memory_server
   ```

### Import Errors

If you see `ModuleNotFoundError`:

```bash
# Install in development mode
pip install -e .
```

---

## References

This project draws inspiration from:

- **[MemPalace](https://github.com/mempathy-labs/mempalace)** — Rule-based extraction patterns, 96.6% LongMemEval benchmark
- **[Claude-Mem](https://github.com/thedotmack/claude-mem)** — Hook lifecycle design, MCP integration patterns

---

## License

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

[python-shield]: https://img.shields.io/badge/Python-3.10%2B-blue
[python-link]: https://python.org
[license-shield]: https://img.shields.io/badge/License-MIT-green
[license-link]: LICENSE
[falkordb-shield]: https://img.shields.io/badge/FalkorDB-4.0%2B-red
[falkordb-link]: https://falkordb.com.com//img.shields.io/badge/FalkorDB-4.0%2B-red
[falkordb-link]: https://falkordb.com.com