contextos-memory-runtime 1.0.0rc2__py3-none-any.whl

contextos_memory_runtime-1.0.0rc2.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: contextos-memory-runtime
+Version: 1.0.0rc2
+Summary: Local-first personal AI memory runtime
+Author: ContextOS Contributors
+License-Expression: MIT
+Keywords: ai,context,local-first,memory,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp<3,>=2
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: pydantic-settings>=2.5.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: rich>=13.8.0
+Requires-Dist: sqlite-vec>=0.1.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3.0.0; extra == 'embeddings'
+Provides-Extra: lancedb
+Requires-Dist: lancedb>=0.12.0; extra == 'lancedb'
+Provides-Extra: tui
+Requires-Dist: textual>=0.79.0; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# ContextOS
+
+ContextOS is a local-first, model-independent AI memory runtime. It is not a chatbot. It accepts activity through a privacy boundary, extracts candidate facts, resolves temporal state, persists memories in SQLite, and supplies bounded context to a chosen model. A local daemon exposes a CLI and API; optional STDIO MCP and explicitly configured connectors use the same memory pipeline.
+
+## Why it exists
+
+Long conversation histories are expensive and can carry stale or contradictory facts. ContextOS combines lexical and dense retrieval, temporal eligibility, a token-aware selector, and a context compiler. It records what it selected and what it could prove, without claiming that fewer context tokens automatically improve answers or provider billing.
+
+## Quick start
+
+Python 3.12+ is declared; this release has been verified on Windows with Python 3.13. Python 3.12 is not yet validated. Core defaults and the offline demo require no commercial API key, model download, or tokenizer cache.
+
+### Installation
+
+Core lightweight installation (uses deterministic/local capabilities):
+```powershell
+pip install contextos-memory-runtime
+```
+
+Core defaults use hashed deterministic embeddings and word-token accounting labeled `APPROXIMATED`. These embeddings are an offline baseline; SentenceTransformer retrieval quality is not implied. FakeProvider is a local simulation.
+
+Rebuilt RC2 archives are approximately **220 KB for the wheel** and **300 KB for the sdist** (decimal units). These sizes exclude installed dependencies. Run `python tools/validate_release_artifacts.py` after a rebuild for exact byte counts.
+
+With optional local sentence-transformers embeddings extra:
+```powershell
+pip install "contextos-memory-runtime[embeddings]"
+```
+
+Installing the extra does not change defaults. Explicitly set `[embedding]` with `model = "all-MiniLM-L6-v2"` in your ContextOS `config.toml` to select it; first use may download that model unless provisioned locally. Exact context counting is also opt-in: set `[token_counter]` with `encoding = "cl100k_base"` or `"o200k_base"`, and provision its tokenizer cache before offline use. Default `encoding = "deterministic"` needs no tokenizer assets.
+
+For development:
+```powershell
+pip install -e ".[dev]"
+```
+
+### Usage
+
+```powershell
+contextos demo
+contextos start
+contextos doctor
+contextos stats
+"I prefer concise technical explanations." | contextos memories remember
+contextos inspect "What explanation style do I prefer?"
+contextos stop
+```
+
+The daemon listens on loopback by default. Review your local configuration before changing its host, connector roots, MCP permissions, or provider settings. Prefer `memories remember` for private text: a command-line argument may be visible in process lists and shell history.
+
+## Architecture and memory lifecycle
+
+Input flows through privacy scanning, extraction, temporal acceptance, and SQLite persistence. Retrieval reads the memory store through ephemeral BM25 and dense indexes. The graph is a separate deterministic projection. The optimizer selects within a token budget; the compiler turns selected memories into context with fact/provenance evidence. The router sends the prepared request to a configured local or optional remote provider. Graph-assisted retrieval remains opt-in because its ranking performance is mixed in the local benchmark.
+
+See [architecture](docs/architecture.md), [explainability](docs/explainability.md), and [RAG inspector](docs/rag-inspector.md) for exact boundaries. Explainability and inspection describe ContextOS preparation, not an unseen provider wire payload. Provider dispatch is `NOT_ATTEMPTED` during inspection.
+
+## Privacy and integrations
+
+Secret scanning does not universally redact private filesystem paths. Selected graph/provenance output surfaces suppress path-shaped labels; terminal sanitization removes control sequences. These are separate output protections.
+
+Secrets are scanned before accepted memory is stored; the legacy `--skip-secret-scan` request field does not disable that boundary. Metadata dashboards omit memory bodies, prompts, source paths, and credentials by default. Explicit content-view commands can reveal private text on your terminal; use them deliberately. Local storage is not a substitute for OS disk encryption or trusted local-user access.
+
+Credential-free local file and JSON/JSONL connectors must be configured explicitly; none are registered by default. See [connectors](docs/connectors.md). MCP is disabled by default, uses STDIO, and separates read, write, and telemetry permissions; see [MCP](docs/mcp.md). Ollama and compatible local endpoints are first-class options; external providers are optional. FakeProvider supports deterministic tests/demo and is identified as simulated.
+
+## Terminal product
+
+| Command | Purpose |
+| --- | --- |
+| `contextos status`, `health`, `doctor` | Daemon state and non-destructive diagnostics |
+| `contextos stats [--model ID] [--provider ID] [--compare] [--today/--week]` | Measured activity by provider/model and token basis |
+| `contextos monitor [--model ID] [--provider ID]` | Poll the same bounded local dashboard |
+| `contextos inspect "query" [--mode hybrid] [--graph] [--memory UUID] [--compare] [--json]` | Retrieval-to-compiler decision evidence |
+| `contextos explain "query"`, `preview "query"` | Explain or preview context without provider dispatch |
+| `contextos graph stats/search/show` | Projection statistics and bounded graph paths |
+| `contextos memories current/conflicts/history` | Temporal metadata; content is opt-in |
+| `contextos connectors list/status/sync` | Registered connector state and explicit sync |
+| `contextos models list`, `contextos telemetry` | Provider inventory and measured invocation records |
+| `contextos benchmark [--extended]`, `contextos demo` | Isolated synthetic evaluation and offline walkthrough |
+
+The dashboard groups provider and model together and keeps context-token counts separate from provider-reported usage. A reduction bar appears only when a single known context tokenizer basis can be compared. Older telemetry with unknown provenance is not silently combined. `--today` is the current UTC day; `--week` is a rolling seven-day window. Session-wide history is not yet persisted as a distinct aggregate.
+Connector status includes currently tracked source-item count; the existing schema does not retain last-sync accepted/unchanged/failed totals for historical display.
+
+## Evidence and limits
+
+The [benchmark](docs/benchmarking.md) compares full history, vector, hybrid, hybrid+graph, and compiled ContextOS context on ten fixed questions at 100 and 1,000 synthetic memories. It reports relevance ranking and context tokens, not answer quality. The [security](docs/security.md), [performance](docs/performance.md), [demo](docs/demo.md), and [release checklist](docs/release-checklist.md) documents separate measured, simulated, and unverified claims. A 5,000-memory run is opt-in. No cloud deployment or commercial-provider proof is implied by the local test suite.
+
+Answer quality is **NOT VALIDATED**. Live providers have not been comprehensively validated. Graph retrieval stays opt-in because the current synthetic benchmark shows a recall/latency tradeoff. Latest independent cold CLI startup was approximately **2.27 seconds median** on Windows; this is a local measurement, not a guarantee.
+
+## Development
+
+```powershell
+python -m pytest tests -q -ra
+python -m compileall -q src tests
+python -m contextos.benchmarks.final
+python -m pip check
+git diff --check
+```
+
+`make test`, `make lint`, `make typecheck`, and `make check` are available when `make` is installed. The package is currently version 1.0.0-rc2. License: MIT.
+
+Background `contextos start` polls the initialized daemon for up to 10 seconds before reporting success. Existing-daemon readiness requires the health PID to match the verified recorded PID at the configured host and port. Startup and stop share a Windows/POSIX lifecycle lock with a 15-second acquisition timeout; concurrent starters wait, then report the verified daemon as already running. The persistent `contextos.lock` file is reusable and OS lock ownership is released on process exit. PID publication is atomic, and failed startup cleans up only its own process tree and matching PID state. `contextos doctor` can be run immediately after a successful start.

contextos_memory_runtime-1.0.0rc2.dist-info/RECORD

@@ -0,0 +1,93 @@
+contextos/__init__.py,sha256=-13Sf7rvleSFTlEiWQIEdpjhkgtpiPcsqB6OMa8bVT0,89
+contextos/__main__.py,sha256=u1JB0rxx9GEPM9dlOJQQfo1ig_OhbbUaDypqXh7uqok,131
+contextos/demo.py,sha256=zDTfaUBtYPa0d4xTw1Z9QXRU0Fzu0-1JBwLxaqWnSno,10084
+contextos/api/__init__.py,sha256=sEYlM_YSXd-bVkcFPx-kZm2NFJYXGs7TLYgLg7eRrLE,34
+contextos/api/server.py,sha256=bBkPtU_yo40MEWTgDIgyX5inEqkThcJsrui0Ciawcig,7945
+contextos/api/routes/__init__.py,sha256=iMgTYMWdJd8HLFD_MUfi_DR_4jMMAJhGr3ogvc19lIg,41
+contextos/api/routes/desktop.py,sha256=19qKZC_FK9cMDYOllJlD6MpcF3nd56xfUGJMPMdu3gs,14715
+contextos/api/routes/ingest.py,sha256=cnmD9zFgo0wBPTYgZFpHPTLApHMaU3aw0XCe-D1ppdY,514
+contextos/api/routes/memories.py,sha256=gIEXcmOeEzQY9rByZYT6HGX5vwSlcXeKVhTpS-3cJ90,2893
+contextos/api/routes/models.py,sha256=4wUWi_L_fNzwGhmeM5u5smLrDEztqRWmHJMbMSg9qcM,2840
+contextos/api/routes/retrieval.py,sha256=60CH5GiGDKxHg2HjJG9XwGtMrSqYzRVfSwjgcbKlBJU,2927
+contextos/api/routes/system.py,sha256=oe9xCYUE2zMMnxiB7NMAyoPmOnh16Pa7vInkj-uJXCg,8667
+contextos/benchmarks/__init__.py,sha256=x3VXlOJrVXRp7McHPBjaxhp3zvLSdIZVHgyoSW8ZfSA,42
+contextos/benchmarks/compilation.py,sha256=PYLDz5jdq4hXspE9HSU055yyhpfzbAa-NYh6M6cKBZQ,8974
+contextos/benchmarks/connectors.py,sha256=R-sTOG26viEqEANNIsSCSMbvKhCcpU2j8awLma30XgI,14795
+contextos/benchmarks/explainability.py,sha256=yTY-3BrfBeg18JBcig4HeLGk1tzSzYr3H3yOnyevG_8,5050
+contextos/benchmarks/final.py,sha256=knI6vBUYUq9oIgFvy-c6-BscRX4FioSRdjA5Mqd7o60,19864
+contextos/benchmarks/graph.py,sha256=G32J4SY1QH36BZO7bSGxhWFBXYpgV9EgIyLWhWl_ulg,13891
+contextos/benchmarks/graph_adversarial.py,sha256=jaLq5W29bJWor686YTz0rOmNCcJcO0m5EegYuX6w1hE,25023
+contextos/benchmarks/mcp.py,sha256=68Vh_FmzqIUV5rZUOzTweThhgF9i-4DShA1yaI77cNk,13014
+contextos/benchmarks/model_routing.py,sha256=IYl_jRqpJOYa2MUQfh77nY_kPB8vOXth9q3MFhjBoTU,7951
+contextos/benchmarks/optimization.py,sha256=UySiRHctn5Mb3kupRA-q4II4W4hwyrXuAeZKVEodbS0,10767
+contextos/benchmarks/rescue_integration.py,sha256=exVJxw5B0Ff__yINvOIEP4liuQ4pMzKORWeH8sNd7cI,5449
+contextos/benchmarks/retrieval.py,sha256=vHH5adxP4af8AnF4dDAVD4A7IW0FQ_11JY-G79G153w,10673
+contextos/benchmarks/temporal.py,sha256=sQw-IM2DIMnYY1xV5LDodl-GI4eELHW_8zHUwbS5rXo,17186
+contextos/benchmarks/temporal_hotpath.py,sha256=BRn-pkRkvx4GVtLfJ5mfaDn2drzyJSx92HIegtk3Eqk,3126
+contextos/benchmarks/terminal.py,sha256=fO-ikyZ0hOfxynboUsVAUd5ofoDrTdJqG-4YESEg8SM,3002
+contextos/cli/__init__.py,sha256=1nuHg_5BHUWeoI8U6eyyTD3KlsOQZd9IH_7AyFaSU5Y,34
+contextos/cli/app.py,sha256=EhY7orXYFatr8_H6K_Y-30dp5vHzxsah_0eK_yVjYts,40317
+contextos/cli/dashboard.py,sha256=hGftM7lK-KrsbVobxeFYpvjVUJsKvkH2tCmFspTBkvU,7341
+contextos/cli/formatters.py,sha256=Xjj5rTODA-DaYsBdS5L_-xms8J2nHUQpKZFBZYapibY,11611
+contextos/config/__init__.py,sha256=TusAd6of1zmexViKV4bHD-PeRRWUFFYiQeBgxFtrg5M,37
+contextos/config/settings.py,sha256=W529G5j3sB6RlGIFiw4bUWnURvQxWG4n0UUL1aL0xpU,5687
+contextos/connectors/__init__.py,sha256=b5kTn1VzIe79oz6ettsjfSVkl_o9t6bmChIEXrkT20s,314
+contextos/connectors/fake.py,sha256=vZMgN3fB9u2JTXjicFsMrUwIrrgqLFqXoj5VtwZm4S0,628
+contextos/connectors/json_import.py,sha256=8qm7KBLIAKAF2RzZeWRIhm2_TutmTyfUgMuPOE33uIU,4915
+contextos/connectors/local_files.py,sha256=OlTy__WDFfVmsn4mg9HYESTfO96_o_wjkIlfGHNuQ8c,4083
+contextos/connectors/manager.py,sha256=x8GVgCP5G8aVd3gdlTATIeCPEfIsxusImKWhxQh03Bk,12565
+contextos/connectors/models.py,sha256=Sv3zivd23YDyoSe8OsKdD8Y5jfOiTqVug4ROxhIKV2o,2037
+contextos/connectors/protocols.py,sha256=VsaJUmnQfZ8bsDQDYP5ynHeIBUjRF6u9-XZGP_lEwQA,437
+contextos/core/__init__.py,sha256=TnendYkFqWuRCh8MlLNSH4RVMgEce_Cm-tF4CClQS20,2168
+contextos/core/enums.py,sha256=EybSQQ7EUXwOexPmG9_n9mgUmha-5Z-3el4o5BzLF6E,13646
+contextos/core/exceptions.py,sha256=DSCrrtXsa4q0rgtAnkK26te1cFKGDuirteneJGHL6JQ,9414
+contextos/core/models.py,sha256=TxjfuSAIVGqHliPpz-Q068_3ZCMiYtS10Y6cNZAo7dA,43085
+contextos/core/protocols.py,sha256=kt1Nt_Emc02bau6FrvZt-XuYGEzmSxvRr_fa3xYOqIo,16677
+contextos/daemon/__init__.py,sha256=5pqcRo7kVWdHeZJJLTCaBYkX-tLHqY9WpYEA3fSasB0,37
+contextos/daemon/manager.py,sha256=WjJ24xxmCDVjCwSAljlBkUeDSshJRWfSXFNoUL1KgKI,19898
+contextos/daemon/state.py,sha256=8CKxkujrMk5Wq6OnNH-bp1KY8GOWIONpvufZ_8ADNuI,4875
+contextos/daemon/wiring.py,sha256=_e-bIQza1Nm5jFefHnobQLFtWqYRgWpKibfN8iE3NHs,11324
+contextos/embedding/__init__.py,sha256=06UqDDwgpeK6bsP7ln4NBs9jA6uYQ0Q3IGz2XWfbLks,40
+contextos/embedding/deterministic.py,sha256=Ao0pSH_NW3r44bRJL3OnS_LkE7-IzG3MlMVOOyxTP1U,2434
+contextos/embedding/sentence_transformers.py,sha256=_HeMO0dge2XLs2yolThTq8HhHijIFB76OBXviyzEZjs,2632
+contextos/mcp/__init__.py,sha256=L873rgjmXRSnjVQAbmy7oeA9e7rs2c__DXRONMTQt9s,128
+contextos/mcp/server.py,sha256=T_vFNYE5QGnbE-kGQXSHuhNuwmluksXdUexaYKfxvhY,17943
+contextos/providers/__init__.py,sha256=BGKlbx2scaFLj-aCsCo_De1bRMW-15mZGkgZGDooyMo,385
+contextos/providers/fake.py,sha256=uiInP7feSH-OIvaVWP1a4QxJ6BXfoNnrP0tFQYHDFH0,8558
+contextos/providers/ollama.py,sha256=A42DEhTdXj-ezVMzlPDuXbGt8m_I5aGjGuBAkwOKOO4,11251
+contextos/providers/openai_compatible.py,sha256=LHsve38P1UznS9V76MmwU35q3cQ_T2KIQtvZ3hi08Uk,13047
+contextos/services/__init__.py,sha256=N8FbVIxzmZ17MgvI74TS1rjxJhNe3zgECNuQTVDp8H8,39
+contextos/services/compilation.py,sha256=RVNsC9Dw2WiK2ONmFbTt09FhcAhC3gB_O5LttnLjuDs,20688
+contextos/services/explainability.py,sha256=xl34T3Y_J3S4WbLhogVtGhiF12EdzYtkc4euMjqKmwE,26369
+contextos/services/extraction.py,sha256=XrLlnOnt9XMzVnbGD2wNzhqsiJZ6E3yOphRMTEbxmQA,12375
+contextos/services/graph.py,sha256=x46Oo_ExLkeHWj5Sy2f7S_NOWjUaeWyfbXAnqI6Bo5s,22750
+contextos/services/graph_retrieval.py,sha256=xrvwrD54Tw-l5tWKWIM5VuWoFOrDSmgH4eLXOrG9CEY,6246
+contextos/services/ingestion.py,sha256=bMK3bj_Z99CAJQ911-RzAYBu8TC3Pg5koQGTz_R2qNE,5892
+contextos/services/inspection.py,sha256=L3z8A2-EOYaxdqLHGJ0XJavQOgC6XSN07cuUJZVknTo,7298
+contextos/services/memory.py,sha256=VEv7tBxKaO9YUPUSCDKDR5lVIdKWWBndgXYSFMYjwfo,10919
+contextos/services/model_service.py,sha256=g2eezFbyYtzVnWwCcDooqQK44KwwuSjhdrpX3YpnkmQ,18120
+contextos/services/optimization.py,sha256=1AHieWrzJTQM1K798wj-DKAmUQNCHPPsQzpAJuN8JRw,16708
+contextos/services/privacy.py,sha256=pfe64IbB-i-fZl0iaWZmJffvytSBosfZMw_FHUW7VOg,12374
+contextos/services/retrieval.py,sha256=PEy4_QUvAMYUpSUxH5x_8tc1v7QP_k6bc1shllyRPPk,11953
+contextos/services/retrieval_index.py,sha256=Lkz9TG9M4XDkyuHQpraHrZ34XsYr7Y7zHIBdE-1LdQA,3179
+contextos/services/router.py,sha256=cZaRrkXokFcd4et2PD6R9J9SvGSmr3ySAVb3JvcTkOU,13723
+contextos/services/secret_scanner.py,sha256=rDetCAWsCHicSYSOOuia5bLjjvAUdiWMFxn0C8x0Upo,8784
+contextos/services/telemetry_query.py,sha256=f7_AjNnAU7b7ekJzptbvOtoX0xgSP-EZuX2yhxsw1vg,4695
+contextos/services/temporal.py,sha256=I6gyt8i4LJxVVmlaPzkAGBjC_99payjPfv6rDW7JohQ,20947
+contextos/services/token_counter.py,sha256=JFl_VAmRZgKMioywPCcetxR-lvi_Y39K8pIzwzE-u50,6945
+contextos/storage/__init__.py,sha256=phTklvJrUd69BUF7lgVQ2NVB7BFKNg4Ms7m2whjb3WY,38
+contextos/storage/connector_repo.py,sha256=y6ad3b5CacT7PZQxYStss8GVoLpuVshYtDSX4WjEggA,4656
+contextos/storage/database.py,sha256=mmjf-cDpUnIIdNq0P5qivZ94ORwnc1Rg9noVjcd7Mqc,20315
+contextos/storage/event_repo.py,sha256=NoNaD07oJbcOXGnVPsNospJ1cHsLNs8nbqcsUxx0EoM,4753
+contextos/storage/graph_repo.py,sha256=jrh3U5ylF9gzGIQLr96-ERJzGJPmPr7nxn3mbmosXQ0,9855
+contextos/storage/memory_repo.py,sha256=ASuKWAvOPXYb-6b93ac8sJNKEyucJMs6Z66YS3Vpvxg,25351
+contextos/storage/relation_repo.py,sha256=LAUk56ILHvgTjZhtLSfMy-9kNigmW5zl90lztaWTAdo,2958
+contextos/storage/telemetry_repo.py,sha256=lX7oJsqSNcCBrF9lqqwWQsFPmEGoO3jv-BTZcAAtVBE,20313
+contextos/storage/lexical/__init__.py,sha256=L_YYXZKNa7PnunHXTfJdczO2b19nAfdg6ocASIsALFc,49
+contextos/storage/lexical/bm25.py,sha256=wFlIffSi7kpWQYKx-BBs9gBLH1AZeZCrXFfiu_cuDFs,4904
+contextos/storage/vector/__init__.py,sha256=WAmvhhDWIG3oIVFcPXSQAAGJ9Hfv0yt3lEaNCL7QzxM,49
+contextos/storage/vector/in_memory.py,sha256=efc1zetc3ONT3MV188CKaClruu12XVseIJ1LkU0aEmQ,5681
+contextos_memory_runtime-1.0.0rc2.dist-info/METADATA,sha256=DkpBpZEW3RWgtnv6k5MAJM4u439kWBDx9m398BddwQE,9975
+contextos_memory_runtime-1.0.0rc2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+contextos_memory_runtime-1.0.0rc2.dist-info/entry_points.txt,sha256=vgxmd1vwBUH1SXNeOysBxLmhXqyR2UCeLFlxATtG4Ac,95
+contextos_memory_runtime-1.0.0rc2.dist-info/RECORD,,

contextos_memory_runtime-1.0.0rc2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

contextos_memory_runtime-1.0.0rc2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+contextos = contextos.cli.app:main
+contextos-mcp = contextos.mcp.server:main