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.
Install
pip install spectrum-memory
For semantic search (optional):
pip install spectrum-memory[semantic]
For MCP server (Claude, Gemini, Codex):
pip install spectrum-memory[mcp]
Everything:
pip install spectrum-memory[all]
Usage
As a library
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
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):
{
"mcpServers": {
"spectrum": {
"command": "spectrum-mcp-py"
}
}
}
Or with uvx:
{
"mcpServers": {
"spectrum": {
"command": "uvx",
"args": ["spectrum-memory[mcp]", "--", "spectrum-mcp-py"]
}
}
}
API
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 | Node.js core library |
| @natiwo/spectrum-cli | Node.js CLI (spm) |
| @natiwo/spectrum-mcp | Node.js MCP server |
License
Metadata
Release files for spectrum-memory 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| spectrum_memory-0.1.0.tar.gz | 10.5 kB | Without provenance | Details for spectrum_memory-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spectrum_memory-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for spectrum_memory-0.1.0-py3-none-any.whl |
Total release size: 22.5 kB
Release files / spectrum_memory-0.1.0.tar.gz
| Download URL | spectrum_memory-0.1.0.tar.gz |
|---|---|
| Size | 10.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
27be28846ffac38233fa3fd5cbcb14c728748108777dcf4c4e019c130a0537d4
|
|
BLAKE2b-256 checksum How to use checksums |
fb4f670302e81220201e9ca55e201c284b2f96488731d83bf6f0f5c08098afe2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / spectrum_memory-0.1.0-py3-none-any.whl
| Download URL | spectrum_memory-0.1.0-py3-none-any.whl |
|---|---|
| Size | 12.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd78720589af2e1ef09bc51ff373c2aaf42540339d432cdd5587a9cdf7de584b
|
|
BLAKE2b-256 checksum How to use checksums |
86ea53073e3d68467de2e39680a28feb3eb0c165d761b5fde4a3216459e12cf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for spectrum-memory 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.