Metadata-Version: 2.4
Name: memory-os-ai
Version: 4.0.6
Summary: Local project memory shared by MCP clients, with dated decisions and work state
Author-email: Kocupyr Romain <romainsantoli@gmail.com>
License-Expression: LGPL-3.0-or-later
Project-URL: Homepage, https://pypi.org/project/memory-os-ai/
Project-URL: Documentation, https://pypi.org/project/memory-os-ai/#description
Project-URL: Source, https://github.com/romainsantoli-web/Memory-os-ai
Project-URL: Issues, https://github.com/romainsantoli-web/Memory-os-ai/issues
Keywords: mcp,memory,local-first,semantic-search,vscode,copilot,claude,codex,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.GPL-3.0
Requires-Dist: annotated-doc==0.0.4
Requires-Dist: annotated-types==0.7.0
Requires-Dist: anyio==4.12.1
Requires-Dist: attrs==25.4.0
Requires-Dist: certifi==2026.2.25
Requires-Dist: cffi==2.0.0
Requires-Dist: click==8.3.1
Requires-Dist: cryptography==46.0.5
Requires-Dist: faiss-cpu==1.13.2
Requires-Dist: filelock==3.25.0
Requires-Dist: fsspec==2026.2.0
Requires-Dist: h11==0.16.0
Requires-Dist: hf-xet==1.3.2
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpx==0.28.1
Requires-Dist: httpx-sse==0.4.3
Requires-Dist: huggingface-hub==1.5.0
Requires-Dist: idna==3.11
Requires-Dist: jinja2==3.1.6
Requires-Dist: joblib==1.5.3
Requires-Dist: jsonschema==4.26.0
Requires-Dist: jsonschema-specifications==2025.9.1
Requires-Dist: markdown-it-py==4.0.0
Requires-Dist: markupsafe==3.0.3
Requires-Dist: mcp==1.26.0
Requires-Dist: mdurl==0.1.2
Requires-Dist: mpmath==1.3.0
Requires-Dist: networkx==3.6.1
Requires-Dist: numpy==2.4.2
Requires-Dist: packaging==26.3
Requires-Dist: pycparser==3.0
Requires-Dist: pydantic==2.12.5
Requires-Dist: pydantic-core==2.41.5
Requires-Dist: pydantic-settings==2.13.1
Requires-Dist: pygments==2.19.2
Requires-Dist: pyjwt==2.11.0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: python-multipart==0.0.22
Requires-Dist: pyyaml==6.0.3
Requires-Dist: referencing==0.37.0
Requires-Dist: regex==2026.2.28
Requires-Dist: rich==14.3.3
Requires-Dist: rpds-py==0.30.0
Requires-Dist: safetensors==0.7.0
Requires-Dist: scikit-learn==1.8.0
Requires-Dist: scipy==1.17.1
Requires-Dist: sentence-transformers==5.2.3
Requires-Dist: shellingham==1.5.4
Requires-Dist: sse-starlette==3.3.2
Requires-Dist: starlette==0.52.1
Requires-Dist: sympy==1.14.0
Requires-Dist: threadpoolctl==3.6.0
Requires-Dist: tokenizers==0.22.2
Requires-Dist: torch==2.10.0
Requires-Dist: tqdm==4.67.3
Requires-Dist: transformers==5.2.0
Requires-Dist: typer==0.24.1
Requires-Dist: typer-slim==0.24.0
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: typing-inspection==0.4.2
Requires-Dist: uvicorn==0.41.0
Provides-Extra: documents
Requires-Dist: pymupdf>=1.24; extra == "documents"
Provides-Extra: legacy-v3
Requires-Dist: pymupdf>=1.24; extra == "legacy-v3"
Requires-Dist: pytesseract>=0.3; extra == "legacy-v3"
Requires-Dist: python-pptx>=1.0; extra == "legacy-v3"
Requires-Dist: python-docx>=1.1; extra == "legacy-v3"
Requires-Dist: Pillow>=10.0; extra == "legacy-v3"
Requires-Dist: requests>=2.32; extra == "legacy-v3"
Provides-Extra: brief
Requires-Dist: charset-normalizer==3.4.4; extra == "brief"
Requires-Dist: requests==2.32.5; extra == "brief"
Requires-Dist: tiktoken==0.12.0; extra == "brief"
Requires-Dist: urllib3==2.6.3; extra == "brief"
Provides-Extra: ops
Requires-Dist: cryptography==46.0.5; extra == "ops"
Provides-Extra: audio
Requires-Dist: memory-os-ai[legacy-v3]; extra == "audio"
Requires-Dist: openai-whisper>=20231117; extra == "audio"
Requires-Dist: torch>=2.4; extra == "audio"
Requires-Dist: torchaudio>=2.4; extra == "audio"
Provides-Extra: gpu
Requires-Dist: faiss-gpu>=1.7; extra == "gpu"
Requires-Dist: torch>=2.4; extra == "gpu"
Provides-Extra: doc-legacy
Requires-Dist: memory-os-ai[legacy-v3]; extra == "doc-legacy"
Requires-Dist: textract>=1.6; extra == "doc-legacy"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Provides-Extra: cloud-gdrive
Requires-Dist: memory-os-ai[legacy-v3]; extra == "cloud-gdrive"
Requires-Dist: google-api-python-client>=2.100; extra == "cloud-gdrive"
Requires-Dist: google-auth>=2.23; extra == "cloud-gdrive"
Requires-Dist: google-auth-oauthlib>=1.1; extra == "cloud-gdrive"
Provides-Extra: cloud-dropbox
Requires-Dist: memory-os-ai[legacy-v3]; extra == "cloud-dropbox"
Requires-Dist: dropbox>=12.0; extra == "cloud-dropbox"
Provides-Extra: cloud-s3
Requires-Dist: memory-os-ai[legacy-v3]; extra == "cloud-s3"
Requires-Dist: boto3>=1.34; extra == "cloud-s3"
Provides-Extra: cloud-azure
Requires-Dist: memory-os-ai[legacy-v3]; extra == "cloud-azure"
Requires-Dist: azure-storage-blob>=12.19; extra == "cloud-azure"
Provides-Extra: cloud-box
Requires-Dist: memory-os-ai[legacy-v3]; extra == "cloud-box"
Requires-Dist: boxsdk>=3.9; extra == "cloud-box"
Provides-Extra: cloud-b2
Requires-Dist: memory-os-ai[legacy-v3]; extra == "cloud-b2"
Requires-Dist: b2sdk>=2.1; extra == "cloud-b2"
Provides-Extra: cloud-all
Requires-Dist: memory-os-ai[cloud-azure,cloud-b2,cloud-box,cloud-dropbox,cloud-gdrive,cloud-s3]; extra == "cloud-all"
Dynamic: license-file

<!-- mcp-name: io.github.romainsantoli-web/memory-os-ai -->
# Memory OS AI

**A local project memory shared between your assistants: dated decisions, next actions and verifiable history,
under your control.**

Status: **ALPHA**. **Source candidate: 4.0.6** (2026-10-12), not published or deployed.
**Current published release: 4.0.5** (PyPI, 2026-10-11). macOS Apple Silicon first.
The new candidate must pass artifact qualification and a clean-install trial before publication.

## What it does

You work with several AI assistants (Claude Code, Codex, Cursor, Copilot, Grok…). Each one has its own memory, or none.
Memory OS AI is a **local MCP server** that they all share:

- **Resume a project**: on startup, a compact brief (≤ 1,500 tokens) gives the objective, the decisions in force,
  the next action, with open tasks when SQLite/work state is enabled. Compact mode requires the optional offline tokenizer table.
- **Record a decision**: dated, sourced facts; a correction explicitly replaces the old one (history kept).
- **Hand over work**: shared tasks (open / blocked / done) with protection against concurrent writes (CAS),
  so that two assistants do not overwrite each other.

The server needs **no LLM**: your assistant extracts the facts, local search costs no API call.
Note: what your assistant reads in memory then enters **its own** context (cloud if your assistant is in the cloud).

## Install (macOS Apple Silicon, Python ≥ 3.11)

For the **4.0.6 candidate**, use the exact locally qualified wheel in a durable environment.
The clean-install trial is still pending; the following candidate commands require this wheel,
not the current PyPI package:

```bash
python3.11 -m venv .venv-memory-os
.venv-memory-os/bin/python -m pip install '/ABS/PATH/memory_os_ai-4.0.6-py3-none-any.whl[ops,brief]'
.venv-memory-os/bin/memory-os-admin quickstart --clients codex,cursor  # preview: no writes or downloads
# After reviewing the preview, with separate consent for downloads:
.venv-memory-os/bin/memory-os-admin quickstart --clients codex,cursor --apply --download-approved
```

Optional `--demo` explicitly saves/searches a fact in a unique demo project. This verifies the
packaged relay; it does not measure a real handoff between assistants. See the packaged client matrix
in `docs/CLIENTS.md`. Keep the environment for the service; the canonical project registry remains inactive.

**Known fresh-install defect (2026-10-12):** published 4.0.4/4.0.5 allow an incompatible MCP 2.x
resolution, which can prevent the server from starting. Already qualified/pinned installations are
unaffected. Unconstrained fresh installation of these releases is not a qualified onboarding path.
The 4.0.6 candidate fixes dependency resolution, but its replacement clean-install trial is still pending.

For an **existing qualified 4.0.5 installation**, keep its qualified environment.
Before starting the server: explicitly provision Granite (~220.2 MB, revision
`835ad14087e140460703cf0fae09f97d469d65c2`), tiktoken 0.12.0 and the cl100k table (1.68 MB); create a 0600
token with `memory-os-admin token create`; prepare the qualified release commit declaration required by 4.0.5;
then use `memory-os-admin setup` to generate client snippets/service templates and `memory-os-admin doctor`
to check the running installation. **Setup creates the token if needed and prints snippets; it does not install
or start a service or edit client configs.** Model loading is offline by default; a missing model is a failure,
not a silent download. Runtime dependencies (including torch) are additional to model weights; installation
size/time still needs a clean-machine measurement.

**4.0.6 candidate only, not available in PyPI 4.0.5:** document libraries move to `[documents]` and `[legacy-v3]`;
a verified embedded identity removes the manual commit declaration; `memory-os-admin provision` previews
pinned resources and needs `--apply --download-approved` for missing files. The candidate implements
`memory-os-admin quickstart --clients claude-code,codex` as a zero-write preview; explicit `--apply`
configures a new macOS installation, with separate download and demo consent. Existing different services,
non-empty stores and unsafe configs are refused. Client configuration undo is semantic and preserves the
store/service/token/resources. The exact 4.0.6 artifacts and complete onboarding still require qualification
and a clean-install trial before release; they are absent from published 4.0.5.

For **new 4.0.6 quickstart installs**, SQLite with work state/tasks is the default;
`--backend jsonl` is the explicit alternative. Existing installations are never migrated implicitly.
The fresh SQLite default directory is `~/.local/share/memory-os/store`; JSONL retains its historical directory.
The candidate pins the full active runtime closure for macOS arm64 CPython 3.11:
61 core packages plus 4 with brief, including MCP 1.26.0, pydantic 2.12.5, the qualified
transport stack, torch 2.10.0 and the numerical/tokenizer dependencies. Versioned constraints
and the METADATA provenance ledger are embedded; optional cloud/document/dev extras are outside this lock.
Quickstart refuses a different installed profile before activation. A matching version list is an attestation,
not a guarantee of identical computation on every machine. Use the returned `ops_env` for administration
in a fresh shell; quickstart does not change your shell defaults or schedule backup jobs.

Provisioning/quickstart keeps a conservative **5 GB free-disk default**. An explicit operator override
`MEMORY_V4_MIN_FREE_BYTES` must be integer bytes ≥ 3,000,000,000; invalid/lower values are refused.
Preview retains the provisioning-peak + 1 GB margin; the 8.5 GB swap cap is unchanged.
This override is **not a user recommendation**, does not alter historical campaign guards,
and is not persisted in service or client configurations.

## Supported assistants

| Assistant | Configured | Connection verified | Real usage observed |
|---|---|---|---|
| Claude Code | yes | yes | yes (brief at startup, saves, assisted capture) |
| Codex (CLI / ChatGPT app) | yes | yes | yes (saves, tasks) |
| Grok CLI | yes | yes (handshake, tools) | not measured |
| Claude Desktop | yes (edit with the app closed) | to verify | not measured |
| VS Code (Copilot agent mode) | yes | to verify (Copilot Chat extension) | not measured |
| Cursor · Antigravity · Zed · Devin Desktop · Windsurf · Gemini CLI | yes | to verify | not measured |

Definitions: *configured* = valid entry detected by `doctor`; *connection verified* = MCP handshake/tool call
observed; *real usage* = memory used in real work. These levels describe the operator deployment reported on 2026-10-11, not every installation.
The candidate source/sdist includes `docs/CLIENTS.md`; packaged documentation is installed under
`share/doc/memory-os-ai`. No unpublished documentation URL is presented as live.

## Security and control

Local server (`127.0.0.1`), private access token (0600) read by the relay: **never written into a client
configuration**. Memories are data, never instructions. Maintenance operations (consolidation) are refused
without explicit authorization. In SQLite mode (opt-in in 4.0.5): encrypted online backups and a restore test.

## Results, with their conditions

- 4.0.5 qualification: more than 1,600 v4 tests plus the v3 suite; outage/reconnection/no-replay TCP tests,
  and qualification on a copy of the operator store. This is engineering evidence, not a productivity score.
- Compact brief: 400 exact measurements, max 1,349 tokens / 3,678 bytes.
- LongMemEval-S retrieval: C4 Recall@10 0.754 vs BM25 0.712, paired delta +0.042 [0.022, 0.061];
  MiniLM/CPU, 466 evidence clusters, observed questions and conditional intervals: **not independent**.
- BEAM 100K retrieval: C4 0.462 vs BM25 0.445, delta +0.017 [-0.004, +0.040], 20 conversations,
  Granite/CPU: the preregistered recall criterion **failed**. These evaluations differ from the operator
  production profile (Granite, auto/MPS, native precision, batch 32). No official leaderboard claim.
- End-to-end answer pilot: 10 observed questions, C4 0.40 vs BM25 0.20, Codex reader/judge;
  **descriptive only**, different judge from published papers, not a held-out comparison or ranking.
- **No productivity gain measured** to date. L11, the handoff study between assistants, was not run.
  The LongMemEval-S and BEAM results above are descriptive, not official leaderboard scores.

## Limits (ALPHA)

macOS Apple Silicon first; Linux and Windows not qualified. A single machine (no multi-device sync), a single user.
Alternatives: Mem0 (OSS and self-hostable), Zep (managed memory) / Graphiti (open-source temporal graph), Letta (agents with memory), Supermemory
(MCP memory, managed service), native memories of the assistants (some with import/export). Different products; we
claim no superiority: our angle is a local memory shared between existing assistants, with explicit
mutation contracts.

## Older test suites

The 4.0.4 source test suite could overwrite real client MCP configs. HOME/config isolation was fixed and
qualified in 4.0.5. Do not run the 4.0.4 suite against your real home.

## Licence

LGPL-3.0-or-later. Third-party model: IBM Granite embedding (see its licence).
