SCM Memory: Embedded Lifecycle Memory for Agents

SCM gives Python and LangChain agents persistent lifecycle memory without an SCM server, hosted account, or SCM URL. It remembers facts and events, resolves corrections, consolidates during sleep, forgets stale noise, discovers schemas, and reports what changed when it wakes.

Install

pip install scm-memory

No SCM server, hosted account, base URL, or provider key is required.

Embedded Python

from scm import SCM

memory = SCM(user_id="alice")
memory.add_memory("Alice prefers concise answers.")

result = memory.search_memory("communication preference")
print(result["memories"])

memory.sleep("deep")
print(memory.wake_summary()["narrative"])
memory.close()

State is stored atomically under ~/.scm by default. No provider key is required; SCM uses offline extraction and hash embeddings when no model is configured.

LangChain 1.x

pip install "scm-memory[langchain]"

from langchain.agents import create_agent
from scm import SCM

memory = SCM(user_id="alice")
agent = create_agent(
    model=model,
    tools=[...],
    middleware=[memory.langchain()],
)

agent.invoke({"messages": [{"role": "user", "content": "I prefer short answers."}]})

The middleware automatically:

1. Recalls relevant memory before the first model call.
2. Persists human messages with retry-safe message identity.
3. Injects bounded memory and wake context as delimited untrusted data.
4. Registers exactly add_memory, search_memory, sleep, wake_summary, and forget.
5. Reuses the attached agent model for extraction when supported, while retaining an offline fallback.

The one-call helper is equivalent:

from scm.langchain import create_scm_agent

agent = create_scm_agent(model=model, tools=[...], user_id="alice")

Multi-User Applications

Application code supplies identity; the model never chooses it.

from scm import SCM, SCMContext
from scm.langchain import create_scm_agent

memory = SCM(namespace="support-app")
agent = create_scm_agent(model=model, tools=[...], memory=memory)

agent.invoke(
    {"messages": [{"role": "user", "content": "Remember my timezone is IST."}]},
    context=SCMContext(user_id="alice", thread_id="ticket-184"),
)

Set SCM_DATABASE_URL in the deployment environment to use PostgreSQL. Agent code remains unchanged and contains no SCM endpoint.

Five Lifecycle Operations

consolidate remains a backward-compatible alias for sleep.

Persistence and Administration

Local storage uses atomic replacement, checksums, process locking, restrictive permissions, and last-known-good recovery. Optional encryption is enabled with SCM_ENCRYPTION_KEY. PostgreSQL adds revisioned transactions, per-user locks, and database-backed sleep leases for multi-worker deployments.

backup = memory.export_user()
memory.import_user(backup)
memory.delete_user()  # hard deletion

Advanced Surfaces

REST, MCP, and the HTTP client remain supported for remote or non-Python deployments. The JavaScript package is a remote REST client; SCM 1.1 does not claim an embedded JavaScript runtime. See Integrations and Deployment.

Product Verification

python scripts/run_product_qualification.py

The release gate builds and installs the wheel outside the repository, runs plain Python and LangChain without an SCM server, checks lifecycle recovery, exercises the optional REST and JavaScript surfaces, and audits dependencies. It also runs deterministic lineage stress and credential-free multi-agent attribution gates. See Quality Gates and Safety Validation.

Documentation

• Getting Started
• LangChain Guide
• Product Thesis
• Architecture
• Deployment
• Safety Validation
• Research Artifacts

Research

The research paper motivates and evaluates SCM's lifecycle architecture. The product remains honest about the evidence: SCM targets interference, contradiction, schema discovery, curiosity gaps, and idle-time transformation; it is not a claim of universal superiority over retrieval systems.

• Published SCM paper (DOI: 10.5281/zenodo.21323877)
• Repository copy
• Reproducibility
• Versioned artifacts

License

MIT