{"id":51856285,"url":"https://github.com/ellmos-ai/usmc","last_synced_at":"2026-07-24T01:03:49.158Z","repository":{"id":342693253,"uuid":"1163516138","full_name":"ellmos-ai/usmc","owner":"ellmos-ai","description":"Local SQLite memory for LLM agents and cross-agent context sharing","archived":false,"fork":false,"pushed_at":"2026-07-04T06:48:08.000Z","size":142,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T08:22:41.788Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://github.com/ellmos-ai/usmc#readme","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ellmos-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://paypal.me/lukasgeiger2507"]}},"created_at":"2026-02-21T18:47:29.000Z","updated_at":"2026-07-04T06:48:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ellmos-ai/usmc","commit_stats":null,"previous_names":["lukisch/usmc","ellmos-ai/usmc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ellmos-ai/usmc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fusmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fusmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fusmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fusmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ellmos-ai","download_url":"https://codeload.github.com/ellmos-ai/usmc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ellmos-ai%2Fusmc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35822076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-07-24T01:03:48.386Z","updated_at":"2026-07-24T01:03:49.141Z","avatar_url":"https://github.com/ellmos-ai.png","language":"Python","funding_links":["https://paypal.me/lukasgeiger2507"],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"assets/banner.svg\" width=\"100%\" alt=\"USMC Banner\"\u003e\n\n# USMC - United Shared Memory Client\n\n[![CI](https://github.com/ellmos-ai/usmc/actions/workflows/ci.yml/badge.svg)](https://github.com/ellmos-ai/usmc/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)\n\n**Deutsch:** [README_de.md](README_de.md)\n\nUSMC 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.\n\nThis 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.\n\n## Start Here\n\n| What | Where |\n|---|---|\n| Install | `pip install git+https://github.com/ellmos-ai/usmc.git` |\n| Quick start | [Quick Start](#quick-start) below |\n| CLI reference | `usmc --help` |\n| German README | [README_de.md](README_de.md) |\n| Tests | `python -m pytest -q` |\n| Changelog | [CHANGELOG.md](CHANGELOG.md) |\n| Issues / feedback | [GitHub Issues](https://github.com/ellmos-ai/usmc/issues) |\n\n## Why It Exists\n\nLLM agent projects often lose context between runs or duplicate notes across tools. USMC keeps the memory part small and reusable:\n\n- Store persistent facts with confidence scores.\n- Record lessons as problem/solution patterns.\n- Keep session-scoped working notes.\n- Track agent sessions and handoff notes.\n- Generate compact context blocks for prompts.\n- Share one local SQLite database across different agents.\n\nUSMC is Tier 1 of the ellmos family. Rinnsal and BACH build larger orchestration layers on top, but USMC stays focused on memory only.\n\n## Install\n\nFrom GitHub:\n\n```bash\npip install git+https://github.com/ellmos-ai/usmc.git\n```\n\nFrom a local checkout:\n\n```bash\npip install -e .\n```\n\nThe PyPI package name `usmc` is reserved for this project but not yet published. Until the first PyPI release, use the GitHub install form above.\n\n## Quick Start\n\n```python\nfrom usmc import USMCClient\n\nclient = USMCClient(agent_id=\"codex\")\n\nclient.add_fact(\"project\", \"framework\", \"FastAPI\", confidence=0.9)\nclient.add_lesson(\n    title=\"Windows encoding\",\n    problem=\"Python subprocess output used cp1252\",\n    solution=\"Run with PYTHONIOENCODING=utf-8\",\n    severity=\"high\",\n)\nclient.add_working(\"Currently preparing a release checklist\")\n\nprint(client.generate_context())\n```\n\nHigh-level API:\n\n```python\nfrom usmc import api\n\napi.init(agent_id=\"claude\")\napi.remember(\"repo\", \"ellmos-ai/usmc\")\napi.note(\"Audit README and package metadata\")\napi.lesson(\"Marketing check\", \"No search visibility\", \"Use ellmos-usmc wording\")\n\nprint(api.status())\nprint(api.context())\n```\n\nCLI:\n\n```bash\nusmc status\nusmc fact project framework FastAPI --confidence 0.9\nusmc note \"Current task: release polish\"\nusmc lesson \"Encoding bug\" \"cp1252 output\" \"Set PYTHONIOENCODING=utf-8\" --severity high\nusmc context\nusmc changes \"2026-02-28T00:00:00\" --json\n```\n\n## Core Concepts\n\n| Concept | What it stores | Typical use |\n|---|---|---|\n| Facts | Persistent key/value knowledge with confidence | Project facts, system facts, user preferences |\n| Lessons | Reusable problem/solution records with severity | Bugs, operational rules, workflow fixes |\n| Working memory | Temporary active notes | Current task state and scratchpad context |\n| Sessions | Start/end records with handoff notes | Cross-agent continuity |\n| Changes | Pollable update stream | Lightweight sync between agents |\n\n## Multi-Agent Example\n\n```python\nfrom usmc import USMCClient\n\ncodex = USMCClient(db_path=\"shared.db\", agent_id=\"codex\")\nclaude = USMCClient(db_path=\"shared.db\", agent_id=\"claude\")\n\ncodex.add_fact(\"project\", \"status\", \"needs docs\", confidence=0.7)\nclaude.add_fact(\"project\", \"status\", \"docs ready\", confidence=0.95)\n\nprint(codex.get_facts(category=\"project\"))\n```\n\nConfidence merging applies per agent: when the same agent rewrites a fact, the\nhigher-confidence value wins. Different agents keep separate rows for the same\nkey; `get_facts()` returns all of them sorted by confidence (highest first).\n\n## Default Database Location\n\nWithout an explicit `db_path`, USMC stores its database per system under\n`~/.usmc/usmc_memory.db` (created on first use). Override the location with\nthe `USMC_DB` environment variable or an explicit `db_path=` / `--db` argument.\nThis keeps the database out of your project folder and out of cloud-synced\nworking directories.\n\n## Database Schema\n\n- `usmc_facts` - persistent facts with confidence scores\n- `usmc_lessons` - lessons learned with severity\n- `usmc_working` - temporary notes, context, scratchpad\n- `usmc_sessions` - agent session tracking\n- `usmc_meta` - internal schema version\n\nThe database is plain SQLite. There is no daemon, broker, cloud service, or external runtime dependency.\n\n## Positioning\n\nUSMC is deliberately smaller than full agent platforms:\n\n| Project type | Scope | USMC role |\n|---|---|---|\n| Agent frameworks | Tools, planning, orchestration, execution | Add shared memory underneath |\n| Chat assistants | Conversation loop and UI | Store durable knowledge outside chat history |\n| MCP servers | Tool exposure over protocol | Use USMC as local memory backend |\n| BACH / Rinnsal | ellmos orchestration layers | USMC is the reusable memory primitive |\n\n## Development\n\n```bash\npython -m pytest -q\npython -m compileall -q usmc tests\npython -m build\n```\n\n## Related Projects\n\n- [Rinnsal](https://github.com/ellmos-ai/rinnsal) - compact ellmos orchestration layer\n- [BACH](https://github.com/ellmos-ai/bach) - full text-based LLM operating system\n- [ellmos-stack](https://github.com/ellmos-ai/ellmos-stack) - deployment and ecosystem context\n\n## License\n\nMIT License - Copyright (c) 2026 Lukas Geiger\n\n## Liability\n\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fellmos-ai%2Fusmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fellmos-ai%2Fusmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fellmos-ai%2Fusmc/lists"}