Metadata-Version: 2.4
Name: longmem
Version: 0.1.2
Summary: Persistent cross-project memory for Cursor and Claude Code — stores problem/solution pairs with semantic search
Project-URL: Homepage, https://github.com/marerem/longmem
Project-URL: Bug Tracker, https://github.com/marerem/longmem/issues
License: MIT
License-File: LICENSE
Keywords: claude-code,cursor,embeddings,lancedb,llm,mcp,memory,ollama,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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.11
Requires-Dist: fastmcp<4,>=3.2.4
Requires-Dist: httpx>=0.27.0
Requires-Dist: lancedb>=0.17.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyarrow>=14.0.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/marerem/longmem/main/longmem_github_logo.svg" alt="longmem" width="480"/>

**Cross-project memory for AI coding assistants.**  
Stop solving the same problems twice.

[![PyPI](https://img.shields.io/pypi/v/longmem?color=blue)](https://pypi.org/project/longmem/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://github.com/marerem/longmem/actions/workflows/test.yml/badge.svg)](https://github.com/marerem/longmem/actions)
[![Coverage](https://codecov.io/gh/marerem/longmem/branch/main/graph/badge.svg)](https://codecov.io/gh/marerem/longmem)
[![Open Issues](https://img.shields.io/github/issues/marerem/longmem)](https://github.com/marerem/longmem/issues)
[![Closed Issues](https://img.shields.io/github/issues-closed/marerem/longmem?color=green)](https://github.com/marerem/longmem/issues?q=is%3Aissue+is%3Aclosed)

</div>

---

Your AI solves the same bug in a different project six months later. Writes the same boilerplate. Explains the same pattern. You already knew the answer.

**longmem** gives your AI a persistent memory that works across every project and every session. Before reasoning from scratch, it searches what you've already solved. After something works, it saves it. The longer you use it, the less you repeat yourself.

```
You describe a problem
        │
        ▼
  search_similar()   ──── match found (≥85%) ────▶  cached solution + edge cases
        │
    no match
        │
        ▼
  AI reasons from scratch
        │
   "it works"
        │
        ▼
  confirm_solution()  ──── saved for every future project
```

---

## Why longmem

| | longmem | others |
|---|---|---|
| **Cost** | Free — local [Ollama](https://ollama.com) embeddings | Requires API calls per session |
| **Privacy** | Nothing leaves your machine | Sends observations to external APIs |
| **Process** | Starts on demand, no daemon | Background worker + open port required |
| **IDE support** | Cursor + Claude Code | Primarily one IDE |
| **Search** | Hybrid: semantic + keyword (FTS5) | Vector-only or keyword-only |
| **Teams** | Export / import / shared DB path / S3 | Single-user |
| **License** | MIT | AGPL / proprietary |

---

## Quickstart

**1. Install**

```bash
pipx install longmem
```

**2. Setup** — checks Ollama, pulls the embedding model, writes your IDE config

```bash
longmem init
```

**3. Activate in each project** — copies the rules file that tells the AI how to use memory

```bash
cd your-project
longmem install
```

**4. Restart your IDE.** Memory tools are now active on every chat.

> **Need Ollama?** Install from [ollama.com](https://ollama.com), then `ollama pull nomic-embed-text`. Or use OpenAI — see [Configuration](#configuration).

---

## How it works

longmem is an [MCP](https://modelcontextprotocol.io) server. Your IDE starts it on demand. Two rules drive the workflow:

**Rule 1 — search first.** Before the AI reasons about any bug or question, it calls `search_similar`. If a match is found (cosine similarity ≥ 85%), the cached solution is returned with any edge-case notes. Below the threshold, the AI solves normally.

**Rule 2 — save on success.** When you confirm something works, the AI calls `confirm_solution`. One parameter — just the solution text. Problem metadata is auto-filled from the earlier search.

The rules file (`longmem.mdc` for Cursor, `CLAUDE.md` for Claude Code) wires this up automatically. No manual prompting.

**AI forgot to save?** Run `longmem review` — an interactive CLI to save any solution in 30 seconds.

---

## CLI

| Command | What it does |
|---------|-------------|
| `longmem init` | One-time setup: Ollama check, model pull, writes IDE config |
| `longmem install` | Copy rules into the current project |
| `longmem status` | Config, Ollama reachability, entry count, DB size |
| `longmem export [file]` | Dump all entries to JSON — backup or share |
| `longmem import <file>` | Load a JSON export — onboard teammates or migrate machines |
| `longmem review` | Manually save a solution when the AI forgot |

`longmem` with no arguments starts the MCP server (used by your IDE).

---

## Configuration

Config lives at `~/.longmem/config.toml`. All fields are optional — defaults work with a local Ollama instance.

### Switch to OpenAI embeddings

```toml
embedder       = "openai"
openai_model   = "text-embedding-3-small"
openai_api_key = "sk-..."   # or set OPENAI_API_KEY
```

Install the extra: `pip install 'longmem[openai]'`

### Team shared database

Point every team member's config at the same path:

```toml
# NFS / shared drive
db_path = "/mnt/shared/longmem/db"
```

Or use cloud storage:

```toml
# S3 (uses AWS env vars)
db_uri = "s3://my-bucket/longmem"

# LanceDB Cloud
db_uri = "db://my-org/my-db"
lancedb_api_key = "ldb_..."   # or set LANCEDB_API_KEY
```

No shared mount? Use `longmem export` / `longmem import` to distribute a snapshot.

### Tuning

```toml
similarity_threshold = 0.85   # minimum score to surface a cached result (default 0.85)
duplicate_threshold  = 0.95   # minimum score to block a save as a near-duplicate (default 0.95)
```

---

## MCP tools

The server exposes 11 tools. The two you interact with most:

- **`search_similar`** — semantic + keyword hybrid search. Returns ranked matches with similarity scores, edge cases, and a `keyword_match` flag when the hit came from exact text rather than vector similarity.
- **`confirm_solution`** — saves a solution with one parameter. Problem metadata auto-filled from the preceding search.

Full list: `save_solution`, `correct_solution`, `enrich_solution`, `add_edge_case`, `search_by_project`, `delete_solution`, `rebuild_index`, `list_recent`, `stats`.

Call `rebuild_index` once you reach 256+ entries to compact the database and build the ANN index for faster search.

---

## Category reference

Categories pre-filter before vector search — keeps retrieval fast at any scale.

| Category | Use for |
|---|---|
| `ci_cd` | GitHub Actions, Jenkins, GitLab CI, build failures |
| `containers` | Docker, Kubernetes, Helm, OOM kills |
| `infrastructure` | Terraform, Pulumi, CDK, IaC drift |
| `cloud` | AWS/GCP/Azure SDK, IAM, quota errors |
| `networking` | DNS, TLS, load balancers, timeouts, proxies |
| `observability` | Logging, metrics, tracing, Prometheus, Grafana |
| `auth_security` | OAuth, JWT, RBAC, secrets, CVEs |
| `data_pipeline` | Airflow, Prefect, Dagster, ETL, data quality |
| `ml_training` | GPU/CUDA, distributed training, OOM |
| `model_serving` | vLLM, Triton, inference latency, batching |
| `experiment_tracking` | MLflow, W&B, DVC, reproducibility |
| `llm_rag` | Chunking, embedding, retrieval, reranking |
| `llm_api` | Rate limits, token cost, prompt engineering |
| `vector_db` | Pinecone, Weaviate, Qdrant, LanceDB |
| `agents` | LangChain, LlamaIndex, tool-calling, agent memory |
| `database` | SQL/NoSQL, migrations, slow queries |
| `api` | REST, GraphQL, gRPC, versioning |
| `async_concurrency` | Race conditions, event loops, deadlocks |
| `dependencies` | Version conflicts, packaging, lock files |
| `performance` | Profiling, memory leaks, caching |
| `testing` | Flaky tests, mocks, integration vs unit |
| `architecture` | Design patterns, service boundaries, refactoring |
| `other` | When nothing above fits |

---

## Contributing

```bash
git clone https://github.com/mariia-eremina/longmem
cd longmem
uv sync --group dev
uv run pytest
```

Pull requests welcome — bug fixes, features, docs, tests.

---

## License

MIT — see [LICENSE](LICENSE).
