Metadata-Version: 2.4
Name: engrama
Version: 0.13.0
Summary: Graph-based long-term memory framework for AI agents (SQLite default, Neo4j optional)
Project-URL: Homepage, https://github.com/scops/engrama
Project-URL: Repository, https://github.com/scops/engrama
Project-URL: Issues, https://github.com/scops/engrama/issues
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,graph,knowledge-graph,mcp,memory,neo4j,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlite-vec>=0.1
Provides-Extra: all
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: fastmcp<4,>=3.2.0; extra == 'all'
Requires-Dist: langchain-community>=0.2; extra == 'all'
Requires-Dist: langchain>=0.2; extra == 'all'
Requires-Dist: mcp>=1.8; extra == 'all'
Requires-Dist: neo4j>=5.26.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-community>=0.2; extra == 'langchain'
Requires-Dist: langchain>=0.2; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: fastmcp<4,>=3.2.0; extra == 'mcp'
Requires-Dist: mcp>=1.8; extra == 'mcp'
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.26.0; extra == 'neo4j'
Provides-Extra: rest
Requires-Dist: fastapi>=0.110; extra == 'rest'
Requires-Dist: uvicorn>=0.29; extra == 'rest'
Description-Content-Type: text/markdown

# Engrama

> Graph-based long-term memory framework for AI agents.

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![Backend](https://img.shields.io/badge/backend-SQLite_%7C_Neo4j-green.svg)](docs/backends.md)
[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha%20%C2%B7%20install%20from%20source-orange.svg)](#quick-start-sqlite-zero-dep)

Engrama gives any AI agent persistent, structured memory backed by a
**knowledge graph**. Instead of flat key-value stores or opaque vector
databases, Engrama stores **entities**, **observations**, and
**relationships** — and lets agents traverse that graph to reason about
their accumulated knowledge.

Two backends are first-class:

- **SQLite + `sqlite-vec`** (default since 0.9) — single file, zero
  external services, `git clone` + `uv sync` and you're running
  (Engrama is not yet on PyPI; install from source).
- **Neo4j 5.26 LTS** (opt-in) — for multi-process production setups,
  large-scale vector search, or teams that already use Cypher.

The data model is identical on both. See **[docs/backends.md](docs/backends.md)**
for a full decision guide; the rest of this README assumes the SQLite
default.

Inspired by Karpathy's second-brain concept, but built for agents
instead of humans — and with graphs instead of wikis.

---

## Why graphs?

| | Flat JSON / KV | Vector DB | **Engrama (Graph)** |
|---|---|---|---|
| Relationship queries | ❌ | ❌ | ✅ native |
| Scales to 10k+ memories | ❌ slow | ✅ | ✅ |
| Works without embeddings | ✅ | ❌ | ✅ (optional) |
| Local-first / private | ✅ | depends | ✅ |
| Zero external services | ✅ | ❌ | ✅ (SQLite) |
| "What projects use FastMCP?" | full scan | approximate | 1-hop traversal |

---

## Prerequisites

You need two things to run on the default SQLite backend. **Docker is
not required** unless you opt into Neo4j.

| Requirement | Version | How to check | Install guide |
|---|---|---|---|
| **Python** | 3.11 or newer | `python --version` | [python.org/downloads](https://www.python.org/downloads/) |
| **uv** (Python package manager) | any recent | `uv --version` | [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) |

> **Windows users:** after installing Python, make sure "Add Python to
> PATH" is checked. After installing uv, you may need to restart your
> terminal.

**Optional:**

- [Obsidian](https://obsidian.md/) — for vault sync features.
- A local embedder for semantic search.
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) —
  only if you opt into the Neo4j backend.

---

## Quick start (SQLite, zero-dep)

### Step 1: Clone and install

```bash
git clone https://github.com/scops/engrama
cd engrama
uv sync
```

### Step 2: Initialise the schema

```bash
uv run engrama init --profile developer
```

### Step 3: Verify

```bash
uv run engrama verify
```

### Step 4: Use it

**A) From Python:**
```python
from engrama import Engrama

with Engrama() as eng:
    eng.remember("Technology", "FastAPI", "High-performance async framework")
    eng.associate("MyProject", "Project", "USES", "FastAPI", "Technology")
    results = eng.search("microservices")
```

**B) From the command line:**
```bash
uv run engrama search "FastAPI"
uv run engrama reflect
```

---

## Quick start (Neo4j, opt-in)

If you need multi-process writes, very large vector indexes, or an existing Cypher toolchain, install with the Neo4j extra:

```bash
git clone https://github.com/scops/engrama
cd engrama
uv sync --extra neo4j
```

Configure your credentials by copying `.env.example` to `.env` and setting `GRAPH_BACKEND=neo4j`. Start Neo4j with `docker compose up -d`, and then initialize the schema:

```bash
uv run engrama init --profile developer
uv run engrama verify
```

---

## 📚 Full Documentation

All further details, including **MCP integration (Claude Desktop)**, **Obsidian sync**, **Architecture**, and the complete **API Reference**, are available in the official documentation.

👉 **[Read the Full Documentation](https://scops.github.io/engrama/)**
