147 lines
3.2 KiB
Markdown
147 lines
3.2 KiB
Markdown
# 🧠 neomem
|
||
|
||
**neomem** is a local-first vector memory engine derived from the open-source **Mem0** project.
|
||
It provides persistent, structured storage and semantic retrieval for AI companions like **Lyra** — with zero cloud dependencies.
|
||
|
||
---
|
||
|
||
## 🚀 Overview
|
||
|
||
- **Origin:** Forked from Mem0 OSS (Apache 2.0)
|
||
- **Purpose:** Replace Mem0 as Lyra’s canonical on-prem memory backend
|
||
- **Core stack:**
|
||
- FastAPI (API layer)
|
||
- PostgreSQL + pgvector (structured + vector data)
|
||
- Neo4j (entity graph)
|
||
- **Language:** Python 3.11+
|
||
- **License:** Apache 2.0 (original Mem0) + local modifications © 2025 ServersDown Labs
|
||
|
||
---
|
||
|
||
## ⚙️ Features
|
||
|
||
| Layer | Function | Notes |
|
||
|-------|-----------|-------|
|
||
| **FastAPI** | `/memories`, `/search` endpoints | Drop-in compatible with Mem0 |
|
||
| **Postgres (pgvector)** | Memory payload + embeddings | JSON payload schema |
|
||
| **Neo4j** | Entity graph relationships | auto-linked per memory |
|
||
| **Local Embedding** | via Ollama or OpenAI | configurable in `.env` |
|
||
| **Fully Offline Mode** | ✅ | No external SDK or telemetry |
|
||
| **Dockerized** | ✅ | `docker-compose.yml` included |
|
||
|
||
---
|
||
|
||
## 📦 Requirements
|
||
|
||
- Docker + Docker Compose
|
||
- Python 3.11 (if running bare-metal)
|
||
- PostgreSQL 15+ with `pgvector` extension
|
||
- Neo4j 5.x
|
||
- Optional: Ollama for local embeddings
|
||
|
||
**Dependencies (requirements.txt):**
|
||
```txt
|
||
fastapi==0.115.8
|
||
uvicorn==0.34.0
|
||
pydantic==2.10.4
|
||
python-dotenv==1.0.1
|
||
psycopg>=3.2.8
|
||
ollama
|
||
```
|
||
|
||
---
|
||
|
||
## 🧩 Setup
|
||
|
||
1. **Clone & build**
|
||
```bash
|
||
git clone https://github.com/serversdown/neomem.git
|
||
cd neomem
|
||
docker compose -f docker-compose.neomem.yml up -d --build
|
||
```
|
||
|
||
2. **Verify startup**
|
||
```bash
|
||
curl http://localhost:7077/docs
|
||
```
|
||
Expected output:
|
||
```
|
||
✅ Connected to Neo4j on attempt 1
|
||
INFO: Uvicorn running on http://0.0.0.0:7077
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 API Endpoints
|
||
|
||
### Add Memory
|
||
```bash
|
||
POST /memories
|
||
```
|
||
```json
|
||
{
|
||
"messages": [
|
||
{"role": "user", "content": "I like coffee in the morning"}
|
||
],
|
||
"user_id": "brian"
|
||
}
|
||
```
|
||
|
||
### Search Memory
|
||
```bash
|
||
POST /search
|
||
```
|
||
```json
|
||
{
|
||
"query": "coffee",
|
||
"user_id": "brian"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🗄️ Data Flow
|
||
|
||
```
|
||
Request → FastAPI → Embedding (Ollama/OpenAI)
|
||
↓
|
||
Postgres (payload store)
|
||
↓
|
||
Neo4j (graph links)
|
||
↓
|
||
Search / Recall
|
||
```
|
||
|
||
---
|
||
|
||
## 🧱 Integration with Lyra
|
||
|
||
- Lyra Relay connects to `neomem-api:8000` (Docker) or `localhost:7077` (local).
|
||
- Identical endpoints to Mem0 mean **no code changes** in Lyra Core.
|
||
- Designed for **persistent, private** operation on your own hardware.
|
||
|
||
---
|
||
|
||
## 🧯 Shutdown
|
||
|
||
```bash
|
||
docker compose -f docker-compose.neomem.yml down
|
||
```
|
||
Then power off the VM or Proxmox guest safely.
|
||
|
||
---
|
||
|
||
## 🧾 License
|
||
|
||
neomem is a derivative work based on the **Mem0 OSS** project (Apache 2.0).
|
||
It retains the original Apache 2.0 license and adds local modifications.
|
||
© 2025 ServersDown Labs / Terra-Mechanics.
|
||
All modifications released under Apache 2.0.
|
||
|
||
---
|
||
|
||
## 📅 Version
|
||
|
||
**neomem v0.1.0** — 2025-10-07
|
||
_Initial fork from Mem0 OSS with full independence and local-first architecture._
|