Metadata-Version: 2.4
Name: scm-memory
Version: 1.0.0
Summary: SCM Memory: embedded lifecycle memory for Python and LangChain agents.
Author-email: Saish Shinde <saish.shinde.jb@gmail.com>
Maintainer-email: Saish Shinde <saish.shinde.jb@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/clyrai/SCM_OpenSource
Project-URL: Documentation, https://github.com/clyrai/SCM_OpenSource/blob/main/docs/README.md
Project-URL: Paper, https://doi.org/10.5281/zenodo.21323877
Project-URL: Changelog, https://github.com/clyrai/SCM_OpenSource/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/clyrai/SCM_OpenSource/issues
Keywords: llm,memory,agent,lifelong-learning,consolidation,sleep,mcp,rag,agent-memory
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.139.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: pydantic>=2.0
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: requests>=2.34.2
Requires-Dist: urllib3>=2.7.0
Requires-Dist: idna>=3.15
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: ollama>=0.1.0
Requires-Dist: mcp>=1.28.1
Requires-Dist: cryptography>=48.0.1
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: python-multipart>=0.0.31
Requires-Dist: filelock>=3.13
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == "llm"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
Requires-Dist: pgvector>=0.3.0; extra == "postgres"
Provides-Extra: langchain
Requires-Dist: langchain<2,>=1; extra == "langchain"
Requires-Dist: langchain-core<2,>=1; extra == "langchain"
Requires-Dist: langgraph<2,>=1; extra == "langchain"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: ollama>=0.1.0; extra == "all"
Requires-Dist: psycopg2-binary>=2.9; extra == "all"
Requires-Dist: pgvector>=0.3.0; extra == "all"
Requires-Dist: langchain<2,>=1; extra == "all"
Requires-Dist: langchain-core<2,>=1; extra == "all"
Requires-Dist: langgraph<2,>=1; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: jsonschema>=4.0; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install scm-memory
```

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

## Embedded Python

```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

```bash
pip install "scm-memory[langchain]"
```

```python
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:

```python
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.

```python
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

| Operation | Purpose |
|---|---|
| `add_memory` | Persist a fact, event, preference, or observation. |
| `search_memory` | Recall relevant memory and update access state. |
| `sleep` | Consolidate, discover schemas, resolve interference, and forget. |
| `wake_summary` | Report what changed during sleep or idle time. |
| `forget` | Suppress one memory while preserving audit lineage. |

`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.

```python
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.0 does not
claim an embedded JavaScript runtime. See
[Integrations](docs/INTEGRATIONS.md) and [Deployment](docs/DEPLOYMENT.md).

## Product Verification

```bash
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.
See [Quality Gates](docs/QUALITY_GATES.md).

## Documentation

- [Getting Started](docs/GETTING_STARTED.md)
- [LangChain Guide](docs/LANGCHAIN_GUIDE.md)
- [Product Thesis](docs/PRODUCT.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Deployment](docs/DEPLOYMENT.md)
- [Research Artifacts](docs/ARTIFACTS.md)

## 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)](https://doi.org/10.5281/zenodo.21323877)
- [Repository copy](research/SCM_Final_Paper.pdf)
- [Reproducibility](docs/REPRODUCIBILITY.md)
- [Versioned artifacts](https://github.com/clyrai/SCM_OpenSource/releases)

## License

[MIT](LICENSE)
