Metadata-Version: 2.4
Name: spectrum-memory
Version: 0.1.0
Summary: Persistent semantic memory for AI agents. Local-first, SQLite, embeddings.
Project-URL: Homepage, https://github.com/Natiwo/spectrum
Project-URL: Repository, https://github.com/Natiwo/spectrum
Project-URL: Documentation, https://github.com/Natiwo/spectrum
Author-email: Claudiomar Estevam <claudio@natiwo.com.br>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,embeddings,llm,mcp,memory,semantic-search,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: mcp[cli]>=1.0.0; extra == 'all'
Requires-Dist: sentence-transformers>=3.0.0; extra == 'all'
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0.0; extra == 'mcp'
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=3.0.0; extra == 'semantic'
Description-Content-Type: text/markdown

<div align="center">

# spectrum-memory

**Persistent semantic memory for AI agents — Python edition.**

Give your AI memory that survives between sessions.
Local-first. SQLite. Embeddings. Zero cloud dependency.

[![PyPI](https://img.shields.io/pypi/v/spectrum-memory)](https://pypi.org/project/spectrum-memory/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Natiwo/spectrum/blob/main/LICENSE)

</div>

---

## Install

```bash
pip install spectrum-memory
```

For semantic search (optional):

```bash
pip install spectrum-memory[semantic]
```

For MCP server (Claude, Gemini, Codex):

```bash
pip install spectrum-memory[mcp]
```

Everything:

```bash
pip install spectrum-memory[all]
```

## Usage

### As a library

```python
from spectrum_memory import Spectrum, MemoryInput

memory = Spectrum()

# save
memory.save(MemoryInput(
    scope="project:my-app",
    key="architecture",
    value="PostgreSQL for ACID. Redis for caching. Next.js 15 frontend.",
    tags=["stack", "database"]
))

# retrieve
arch = memory.get("project:my-app", "architecture")

# keyword search
results = memory.search("database", scope="project:my-app")

# semantic search (finds by meaning, not just words)
similar = memory.search_semantic("which database did we choose?")

# list all memories in a scope
all_mems = memory.list("project:my-app")

# list all scopes
scopes = memory.list_scopes()

# done
memory.close()
```

### CLI

```bash
spm save user/name "Claudio, backend dev, TypeScript strict"
spm save project:app/stack "Next.js 15, PostgreSQL, Redis"
spm get project:app/stack
spm search "database"
spm search "which database" --semantic
spm list project:app
spm scopes
spm stats
```

### MCP Server

For Claude Code (`~/.claude.json`):

```json
{
  "mcpServers": {
    "spectrum": {
      "command": "spectrum-mcp-py"
    }
  }
}
```

Or with uvx:

```json
{
  "mcpServers": {
    "spectrum": {
      "command": "uvx",
      "args": ["spectrum-memory[mcp]", "--", "spectrum-mcp-py"]
    }
  }
}
```

## API

```python
memory = Spectrum(
    db_path=None,       # default: ~/.spectrum/spectrum.db
    storage=None,       # custom StorageProvider
    embeddings=None,    # custom EmbeddingProvider
    semantic=True,      # False = no embeddings
)
```

| Method | Returns | Description |
|--------|---------|-------------|
| `save(input)` | `Memory` | Upsert by scope+key |
| `get(scope, key)` | `Memory \| None` | Retrieve by key |
| `list(scope, opts?)` | `list[Memory]` | List with optional prefix/limit |
| `delete(scope, key)` | `bool` | Delete a memory |
| `search(query, scope?, limit?)` | `list[SearchResult]` | Keyword search |
| `search_semantic(query, scope?, limit?, threshold?)` | `list[SearchResult]` | Semantic search |
| `list_scopes()` | `list[ScopeInfo]` | All scopes with count |
| `stats()` | `Stats` | DB statistics |
| `close()` | `None` | Close connection |

## Shared Database

Python and Node.js Spectrum share the same SQLite database (`~/.spectrum/spectrum.db`). Save from Node, read from Python, and vice versa.

## Ecosystem

| Package | What |
|---------|------|
| **spectrum-memory** | Python library + CLI + MCP (you are here) |
| [@natiwo/spectrum](https://www.npmjs.com/package/@natiwo/spectrum) | Node.js core library |
| [@natiwo/spectrum-cli](https://www.npmjs.com/package/@natiwo/spectrum-cli) | Node.js CLI (`spm`) |
| [@natiwo/spectrum-mcp](https://www.npmjs.com/package/@natiwo/spectrum-mcp) | Node.js MCP server |

## License

[MIT](https://github.com/Natiwo/spectrum/blob/main/LICENSE)
