spectrum-memory 0.1.0

Persistent semantic memory for AI agents. Local-first, SQLite, embeddings.

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

MIT