Skip to main content

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 License: MIT


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

MIT

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)

Source distribution for spectrum-memory 0.1.0
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)

Table of built distributions (wheels) for spectrum-memory 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page