# Synapse: Long-term Memory for LLMs

Synapse is a lightweight memory engine designed to give agents and LLMs a permanent "brain." It solves the "goldfish memory" problem by storing important facts, decisions, and preferences in an organized way, retrieving only what is relevant to the current conversation.

Instead of stuffing your entire chat history into a prompt, Synapse uses a smart search system to find exactly what matters. This keeps your context window clean and your token costs low.

---

## How it works

Synapse is designed to be flexible and works in two main ways:

* **Plug-and-play (MCP)**: Connect it to any AI tool that supports the Model Context Protocol (such as Claude Desktop, Cursor, Zed, and others). It works instantly as a set of tools the AI can use to remember things about your projects and preferences.
* **As a Core Engine**: If you are building your own AI application, you can import Synapse directly into your Python project. It handles memory management, semantic search, and versioning without the need for complex vector database setups.

## Main Features

* **Hybrid Retrieval (BM25 + Local Vectors + Recency)**: Combines exact keyword matching with optional local semantic search via fastembed + RRF, prioritized by recency.
* **Automatic Organization**: Hierarchical categories, automatic memory splitting, and semantic conflict resolution.
* **Fast and Local**: Built on SQLite with an in-memory index; sub-500ms retrieval without heavy vector databases.
* **Zero Mandatory Dependencies**: Core engine runs on standard Python 3.10+ and SQLite. No network calls in the search path.

---

## Operating Modes

1. **Base Mode (Zero Dependencies)**: BM25 keyword search + recency decay. Out of the box, zero external packages.
2. **Semantic Hybrid Mode (`pip install fastembed`)**: Fuses BM25 and lightweight ONNX vector embeddings via Reciprocal Rank Fusion (RRF). Handles paraphrasing without PyTorch.
3. **Full Knowledge Graph (`SYNAPSE_LLM_KEY`)**: Enables asynchronous extraction of entity relationships and session consolidation.

---

## Getting Started

### Prerequisites
* Python 3.10+

### 1. Installation
```bash
# Clone the repository
git clone https://github.com/RaffaelFerro/synapse.git
cd synapse

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Optional: install MCP server support
pip install -r requirements.txt

# Optional: install lightweight semantic hybrid search
pip install fastembed
```

### 2. Standalone CLI Usage
You can manage your memory manually via the terminal:
```bash
# Initialize the database
python3 -m synapse init

# Add a memory
python3 -m synapse add --path "project/stack" --title "Database" --content "Using SQLite and RAM Index."

# Search
python3 -m synapse search --prompt "what database are we using?"
```

### 3. MCP Server Configuration
To use Synapse with tools like Claude Desktop or Cursor, add it to your configuration file:

**Example (`claude_desktop_config.json`):**
```json
{
  "mcpServers": {
    "synapse_memory": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "synapse.mcp_server"],
      "env": {
         "PYTHONPATH": "/absolute/path/to/synapse_directory"
      }
    }
  }
}
```

---

## Maintenance
Keep your memory engine healthy with built-in maintenance tools:

```bash
# Run Garbage Collector (clean up obsolete data)
python3 -m synapse gc

# Database and Index optimization
python3 -m synapse optimize
```

## Testing
```bash
python3 -m unittest discover -s tests -p 'test_*.py'
```

## License
MIT. See `LICENSE` for details.