Metadata-Version: 2.4
Name: nexusmemo
Version: 0.1.1
Summary: Local-first AI memory layer that gives LLMs persistent, structured memory
Project-URL: Homepage, https://github.com/Byhunny/nexusmemo
Project-URL: Repository, https://github.com/Byhunny/nexusmemo
Project-URL: Issues, https://github.com/Byhunny/nexusmemo/issues
Author-email: Byhunny <tansusam91@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,knowledge-graph,llm,mcp,memory
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: networkx>=3.3
Requires-Dist: numpy>=1.26.0
Requires-Dist: openai>=1.30.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: local-embeddings
Requires-Dist: sentence-transformers>=3.0.0; extra == 'local-embeddings'
Description-Content-Type: text/markdown

# NexusMemo

Local-first AI memory layer that gives LLMs persistent, structured memory.

> "We are building the memory operating system that turns AI from a temporary assistant into a long-term collaborator."

## Problem

LLMs are stateless. They forget previous sessions, lose architectural context, repeat mistakes, and require repeated explanations. NexusMemo fixes this by building a persistent knowledge graph from your conversations.

## How It Works

```
conversation → entity extraction → relationship graph → retrieval → prompt injection
```

When you tell NexusMemo something, it:
1. **Extracts** entities, relationships, and decisions using LLM
2. **Embeds** the text for semantic search
3. **Builds** a knowledge graph with NetworkX
4. **Stores** everything in a local SQLite database

When you query, it:
1. **Searches** semantically similar memories
2. **Expands** through the knowledge graph
3. **Reranks** by importance and relevance
4. **Compresses** into context ready for LLM injection

## Quick Start

### Install

```bash
pip install -e .
```

### Configure

```bash
cp .env.example .env
# Edit .env and add your OpenAI API key
```

### Use via CLI

```bash
# Add a memory
nexusmemo add "We replaced Airflow with Dagster because DAG maintenance became difficult"

# Search memories
nexusmemo search "What orchestration tool do we use?"

# Check status
nexusmemo status

# Get entity info
nexusmemo entity "Dagster"
```

### Use via API

```bash
# Start the server
nexusmemo serve

# Add memory
curl -X POST http://localhost:8765/memory/add \
  -H "Content-Type: application/json" \
  -d '{"text": "We migrated from MongoDB to PostgreSQL for better ACID compliance"}'

# Query
curl -X POST http://localhost:8765/memory/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What database do we use?"}'
```

### Use with Claude Code (MCP)

```bash
# Add as MCP server
claude mcp add nexusmemo -- nexusmemo mcp

# Or if installed via pip in a specific path:
claude mcp add nexusmemo -- /path/to/venv/bin/nexusmemo mcp
```

Available MCP tools:
- `add_memory` — Store project context
- `search_memory` — Query past memories
- `get_project_context` — Get rich context about a topic
- `find_related` — Explore knowledge graph relationships
- `get_decisions` — Review past decisions
- `memory_status` — Check system stats

## Architecture

```
┌──────────────┐
│   Interfaces │  CLI / FastAPI / MCP Server
├──────────────┤
│     Core     │  NexusMemo orchestration class
├──────────────┤
│   Services   │  Extraction, Embedding, Graph, Importance
├──────────────┤
│   Storage    │  SQLite + NetworkX (in-memory)
└──────────────┘
```

## Tech Stack

- **Python 3.11+** with FastAPI
- **SQLite** for persistent storage
- **NetworkX** for in-memory knowledge graph
- **OpenAI API** for extraction and embeddings
- **MCP SDK** for Claude Code integration

## Database

Four tables:
- `memories` — Raw text with embeddings
- `nodes` — Knowledge graph entities
- `edges` — Relationships between entities
- `decisions` — Project decisions with reasoning

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run API server in dev mode
nexusmemo serve
```

## License

MIT
