https://github.com/ellmos-ai/usmc
Local SQLite memory for LLM agents and cross-agent context sharing
https://github.com/ellmos-ai/usmc
agent-framework agent-memory ai-agent automation cross-agent cross-agent-memory llm llm-agents llm-memory local-ai local-first memory open-source prompt-context python python-cli shared-memory sqlite sqlite-memory zero-dependency
Last synced: 2 days ago
JSON representation
Local SQLite memory for LLM agents and cross-agent context sharing
- Host: GitHub
- URL: https://github.com/ellmos-ai/usmc
- Owner: ellmos-ai
- License: mit
- Created: 2026-02-21T18:47:29.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-07-04T06:48:08.000Z (22 days ago)
- Last Synced: 2026-07-04T08:22:41.788Z (22 days ago)
- Topics: agent-framework, agent-memory, ai-agent, automation, cross-agent, cross-agent-memory, llm, llm-agents, llm-memory, local-ai, local-first, memory, open-source, prompt-context, python, python-cli, shared-memory, sqlite, sqlite-memory, zero-dependency
- Language: Python
- Homepage: https://github.com/ellmos-ai/usmc#readme
- Size: 139 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# USMC - United Shared Memory Client
[](https://github.com/ellmos-ai/usmc/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
**Deutsch:** [README_de.md](README_de.md)
USMC is a zero-dependency Python memory layer for LLM agents. It gives multiple local agents one shared SQLite-backed memory for facts, lessons, working notes, sessions, and compact prompt context.
This repository is the ellmos project `ellmos-ai/usmc`, also described as **ellmos USMC** or **United Shared Memory Client** in search text. It is not related to the United States Marine Corps.
## Start Here
| What | Where |
|---|---|
| Install | `pip install git+https://github.com/ellmos-ai/usmc.git` |
| Quick start | [Quick Start](#quick-start) below |
| CLI reference | `usmc --help` |
| German README | [README_de.md](README_de.md) |
| Tests | `python -m pytest -q` |
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
| Issues / feedback | [GitHub Issues](https://github.com/ellmos-ai/usmc/issues) |
## Why It Exists
LLM agent projects often lose context between runs or duplicate notes across tools. USMC keeps the memory part small and reusable:
- Store persistent facts with confidence scores.
- Record lessons as problem/solution patterns.
- Keep session-scoped working notes.
- Track agent sessions and handoff notes.
- Generate compact context blocks for prompts.
- Share one local SQLite database across different agents.
USMC is Tier 1 of the ellmos family. Rinnsal and BACH build larger orchestration layers on top, but USMC stays focused on memory only.
## Install
From GitHub:
```bash
pip install git+https://github.com/ellmos-ai/usmc.git
```
From a local checkout:
```bash
pip install -e .
```
The PyPI package name `usmc` is reserved for this project but not yet published. Until the first PyPI release, use the GitHub install form above.
## Quick Start
```python
from usmc import USMCClient
client = USMCClient(agent_id="codex")
client.add_fact("project", "framework", "FastAPI", confidence=0.9)
client.add_lesson(
title="Windows encoding",
problem="Python subprocess output used cp1252",
solution="Run with PYTHONIOENCODING=utf-8",
severity="high",
)
client.add_working("Currently preparing a release checklist")
print(client.generate_context())
```
High-level API:
```python
from usmc import api
api.init(agent_id="claude")
api.remember("repo", "ellmos-ai/usmc")
api.note("Audit README and package metadata")
api.lesson("Marketing check", "No search visibility", "Use ellmos-usmc wording")
print(api.status())
print(api.context())
```
CLI:
```bash
usmc status
usmc fact project framework FastAPI --confidence 0.9
usmc note "Current task: release polish"
usmc lesson "Encoding bug" "cp1252 output" "Set PYTHONIOENCODING=utf-8" --severity high
usmc context
usmc changes "2026-02-28T00:00:00" --json
```
## Core Concepts
| Concept | What it stores | Typical use |
|---|---|---|
| Facts | Persistent key/value knowledge with confidence | Project facts, system facts, user preferences |
| Lessons | Reusable problem/solution records with severity | Bugs, operational rules, workflow fixes |
| Working memory | Temporary active notes | Current task state and scratchpad context |
| Sessions | Start/end records with handoff notes | Cross-agent continuity |
| Changes | Pollable update stream | Lightweight sync between agents |
## Multi-Agent Example
```python
from usmc import USMCClient
codex = USMCClient(db_path="shared.db", agent_id="codex")
claude = USMCClient(db_path="shared.db", agent_id="claude")
codex.add_fact("project", "status", "needs docs", confidence=0.7)
claude.add_fact("project", "status", "docs ready", confidence=0.95)
print(codex.get_facts(category="project"))
```
Confidence merging applies per agent: when the same agent rewrites a fact, the
higher-confidence value wins. Different agents keep separate rows for the same
key; `get_facts()` returns all of them sorted by confidence (highest first).
## Default Database Location
Without an explicit `db_path`, USMC stores its database per system under
`~/.usmc/usmc_memory.db` (created on first use). Override the location with
the `USMC_DB` environment variable or an explicit `db_path=` / `--db` argument.
This keeps the database out of your project folder and out of cloud-synced
working directories.
## Database Schema
- `usmc_facts` - persistent facts with confidence scores
- `usmc_lessons` - lessons learned with severity
- `usmc_working` - temporary notes, context, scratchpad
- `usmc_sessions` - agent session tracking
- `usmc_meta` - internal schema version
The database is plain SQLite. There is no daemon, broker, cloud service, or external runtime dependency.
## Positioning
USMC is deliberately smaller than full agent platforms:
| Project type | Scope | USMC role |
|---|---|---|
| Agent frameworks | Tools, planning, orchestration, execution | Add shared memory underneath |
| Chat assistants | Conversation loop and UI | Store durable knowledge outside chat history |
| MCP servers | Tool exposure over protocol | Use USMC as local memory backend |
| BACH / Rinnsal | ellmos orchestration layers | USMC is the reusable memory primitive |
## Development
```bash
python -m pytest -q
python -m compileall -q usmc tests
python -m build
```
## Related Projects
- [Rinnsal](https://github.com/ellmos-ai/rinnsal) - compact ellmos orchestration layer
- [BACH](https://github.com/ellmos-ai/bach) - full text-based LLM operating system
- [ellmos-stack](https://github.com/ellmos-ai/ellmos-stack) - deployment and ecosystem context
## License
MIT License - Copyright (c) 2026 Lukas Geiger
## Liability
This project is an unpaid open-source donation. Liability is limited to intent and gross negligence under Section 521 German Civil Code. Use at your own risk. No warranty, no maintenance guarantee, and no fitness-for-purpose promise are provided.