USMC - United Shared Memory Client

Deutsch: 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.

Note

ellmos USMC (United Shared Memory Client) is the Tier 1 shared memory primitive for local LLM agents in the ellmos AI ecosystem. It provides zero-dependency SQLite-backed persistence for facts, lessons learned, working notes, and prompt context without requiring a background daemon or cloud service.

Start Here

What	Where
Install	pip install git+https://github.com/ellmos-ai/usmc.git
Quick start	Quick Start below
CLI reference	usmc --help
German README	README_de.md
Tests	python -m pytest -q
Changelog	CHANGELOG.md
Issues / feedback	GitHub 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.

Architecture & Data Flow

graph TD
    subgraph Agents ["Local LLM Agents"]
        A1["Agent A (e.g. Codex)"]
        A2["Agent B (e.g. Claude)"]
        A3["Agent C (e.g. Gemini)"]
    end

    subgraph USMC ["USMC (United Shared Memory Client)"]
        API["USMC Client API / CLI"]
        FM["Facts Memory (Key/Value + Confidence)"]
        LM["Lessons Learned (Bugs & Fixes + Severity)"]
        WM["Working Notes & Handoff Context"]
    end

    DB[("SQLite Database (~/.usmc/usmc_memory.db)")]

    A1 -->|add_fact / add_lesson| API
    A2 -->|add_working / context| API
    A3 -->|query changes / facts| API

    API --> FM
    API --> LM
    API --> WM

    FM --> DB
    LM --> DB
    WM --> DB

Loading

Install

From GitHub:

pip install git+https://github.com/ellmos-ai/usmc.git

From a local checkout:

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

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:

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:

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

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

python -m pytest -q
python -m compileall -q usmc tests
python -m build

Related Projects

• Rinnsal - compact ellmos orchestration layer
• BACH - full text-based LLM operating system
• 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.