memorykit 0.6.0__tar.gz

memorykit-0.6.0/.gitignore

@@ -0,0 +1,233 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Claude Code plugin cache / local validation
+.claude/
+*.tq
+*.tvim
+
+# rtk (Rust Token Killer) local config — machine-specific, not published
+.rtk/
+
+# Internal dev process artifacts (brainstorm specs / implementation plans) — kept local, not published
+docs/superpowers/
+
+# MemPalace per-project files (issue #185)
+mempalace.yaml
+entities.json

memorykit-0.6.0/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Changelog
+
+## 0.6.0 — 2026-08-09
+
+- **Package the memory contract, validator, and MCP server as `memorykit`, ready
+  to publish to PyPI** (ADR-0006 item 3, ADR-0009). Nothing is uploaded yet and
+  the name is unclaimed; publishing is a separate, deliberate act. The
+  implementation moved to
+  `src/memorykit/{provider,mcp}.py` and is installable as `memorykit`, which
+  provides the `memorykit` and `memorykit-mcp` console scripts. The package has
+  **no Python package dependencies** — that property is what makes this unit
+  separable from the plugin at all, and it is now enforced by a test rather than
+  a convention. It is not free of *system* dependencies: `validate` and
+  `capture` shell out to `git check-ref-format`, so `git` must be on `PATH`.
+  That is documented rather than removed, because reimplementing Git's refname
+  rules would be an unreviewed reimplementation and skipping the check would
+  silently weaken provenance.
+- The two files moved whole. `memory-provider.py` was not split along its
+  contract/validator/provider/CLI seams: `capture` needs the review-state
+  machine, and the MCP server needs the provider, so no narrower cut is a
+  working unit. Single-file-ness is a property of that script, not an accident.
+- `scripts/memory-provider.py` and `mcp/server.py` remain as launchers, so
+  `hooks/hooks.json`, `.mcp.json`, the slash commands, and every reference doc
+  keep working unchanged. Unlike the `indexkit` launcher, these prefer the
+  **bundled** source over an installed package, so plugin version X always runs
+  provider version X.
+- Fix `_indexkit_root()`, which resolved a fixed `parents[2]`. That is correct
+  for at most one of the two deployment shapes; it now walks ancestors for a
+  directory that actually contains the launcher, and finds nothing (rather than
+  something wrong) in `site-packages`.
+
+## 0.5.5 — 2026-08-09
+
+- Correct the `rag` provider reference, which described a bootstrapped venv as
+  the only runtime and `doctor` as verifying that venv. `indexkit` is published
+  on PyPI, and `doctor` reports `ready` for a packaged install too, so agents
+  loading this reference were giving stale `uv`-only instructions. Also record
+  the one asymmetry that survives: the launcher prefers an existing venv over
+  `PATH`, so a packaged install does not displace a stale venv.
+
+## 0.5.4 — 2026-08-08
+
+- Assess criteria 2 and 5 explicitly for adrkit. The table claimed criteria
+  "1, 3, 6–12" (nine) while the conclusion said 11 of 12, leaving 2 and 5
+  silently unclassified. Both pass; the qualification is now internally complete.
+
+## 0.5.3 — 2026-08-08
+
+- Record adrkit in the provider decision table as a peer corpus rather than a
+  provider, with the trust-model reason it cannot be one and the promotion path
+  from a `type: decision` record to a ratified ADR (ADR-0003).
+
+## 0.5.2 — 2026-08-08
+
+- Fix a real failure in the pre-rename compatibility path. `store_env` and the
+  runtime probe set only `CONTEXT_KIT_INDEXKIT_HOME`, but a legacy `bin/rag`
+  launcher — which `_bundled_executable` can legitimately resolve — reads only
+  `CONTEXT_KIT_LOCAL_RAG_HOME`. With `CONTEXT_KIT_DATA` redirected to the
+  isolated provider store, that launcher looked for its venv inside the store
+  and failed. Both names are now exported to the same resolved path.
+- Restore pre-rename CHANGELOG entries to their original wording, so an old
+  release's notes remain usable for diagnosing that version.
+
+## 0.5.1 — 2026-08-08
+
+- Move the `rag` provider's tested-version pin to indexkit 0.6.x, the release
+  this adapter is exercised against.
+
+## 0.5.0 — 2026-08-08
+
+- Track the `local-rag` → `indexkit` rename (ADR-0007) without breaking existing
+  installs. Provider resolution now accepts both names: `CONTEXT_KIT_INDEXKIT_BIN`
+  with `CONTEXT_KIT_RAG_BIN` as fallback, both `indexkit` and `rag` on PATH, and
+  either sibling plugin directory.
+- Add declarative `legacy_bin_env` / `legacy_executables` to `ProviderSpec`, so the
+  migration is provider data rather than branching in the resolver.
+- The `rag` provider identifier is unchanged; existing configuration keeps working.
+
+## 0.4.0 — 2026-08-05
+
+- **Correct a documented falsehood.** Several docs claimed GitHub Copilot does
+  not run Claude hooks. Verified false against a live Copilot CLI install
+  (1.0.79): Copilot loads a plugin's `hooks/hooks.json` using the same
+  PascalCase event names, honors an `additionalContext` string on stdout, and
+  bootstraps plugin data at `~/.copilot/plugin-data/<marketplace>/<plugin>/`.
+  APM still does not deploy hooks. Docs now state the real host matrix.
+- `wake` is now a provider-neutral session digest built from local records
+  rather than a MemPalace passthrough. Records are the system of record and a
+  provider store is a projection of them, so the digest is identical under
+  `none`, `rag`, and `mempalace`. It is bounded by record count and character
+  budget, ordered by recency, flags drifted or missing sources, and offers
+  `--format text` for injection.
+- Add a `SessionStart` hook that emits that digest as `additionalContext`, so
+  reviewed memory primes a session on both hosts that load hooks. Gated on its
+  own `CONTEXT_KIT_MEMORY_RECALL_ON_START` switch rather than on
+  `AUTO_CAPTURE`, because reading is not writing, and it degrades to `{}`
+  rather than ever failing a session start.
+- Add `audit`, a store-wide sweep for records whose cited source drifted or
+  vanished. It reports and proposes an exact `record-state` command; unlike
+  MemPalace's `sync` it never prunes, because evidence is the reason a memory
+  can be trusted later and a moved file is not proof a decision was wrong.
+- Tool-level hooks are deliberately **not** used. Measured on a real Copilot
+  corpus, `preToolUse` and `postToolUse` fire 23,683 and 35,083 times against
+  ~1,800 for the session boundaries, so hooking them would spawn a process per
+  tool call to capture noise, and would amount to the continuous transcript
+  harvesting the memory contract forbids.
+- Drop the obsolete `wake-up` capability probe. `wake` is now built from local
+  records for every provider, so requiring `wake-up` would refuse a MemPalace
+  install over a command the adapter never calls. Delegation is not restored:
+  MemPalace's `wake-up` returns its own mined L0/L1 context, which is
+  unreviewed, and returning it would violate the active-only, reviewed-only
+  recall contract.
+- Fix venv resolution for the `rag` provider on Copilot. 0.3.0 dropped
+  `CLAUDE_PLUGIN_DATA` because it is plugin-scoped, but that also lost the
+  ability to locate the dependency. Both hosts lay plugin data out as
+  `<root>/<plugin>`, so local-rag's home is resolved as a **sibling** of
+  memory's, and only when it exists.
+
+## 0.3.0 — 2026-08-04
+
+- Add an optional stdio MCP server (`mcp/server.py` plus `.mcp.json`) exposing
+  `memory_recall`, `memory_capture`, and `memory_review`, so hosts that consume
+  skills plus MCP rather than Claude plugins can use durable memory. Standard
+  library only, no daemon, no Claude hooks. It shells out to
+  `memory-provider.py` with exact argv so the CLI and MCP paths cannot drift.
+- The MCP surface can propose memory but **cannot activate it**: `capture`
+  derives initial state from frontmatter, so the server refuses any record that
+  is not `review: proposed`. `sync-provider`, `record-state` promotion, backup
+  pruning, session mining, and destructive operations are not exposed.
+- Add `propose-from-session`, which extracts the human-visible conversation
+  from GitHub Copilot CLI logs into reviewable
+  `context-kit/memory-candidate-v1` candidates. It proposes rather than
+  captures: a transcript is not an atomic memory, so authoring a record stays
+  an explicit judgment step and nothing mined can enter active recall on its
+  own. Dry run is the default.
+- Session extraction keeps only top-level turns. A `user.message` is human
+  only when it carries neither `parentAgentTaskId` nor a `source` field;
+  `assistant.message` requires neither `parentToolCallId` nor
+  `parentAgentTaskId`. Measured across a real 115-session corpus, 611 of 729
+  user events were subagent task prompts and 94 were generated context,
+  leaving 24 genuine human turns — filtering only on a `skill-` prefix would
+  keep 657 and misattribute authorship roughly 27-fold. `reasoningText`,
+  `reasoningOpaque`, and `transformedContent` are never extracted.
+- Mining scans for credential shapes and blocks the write on a finding;
+  `--redact` masks the spans and records a count. Repository, branch, and HEAD
+  anchors are required and never invented, and candidates are project-isolated
+  and write-once.
+- Add a first-party `rag` memory provider backed by the bundled `local-rag`
+  plugin, so **offline semantic recall no longer requires an external memory
+  provider**. MemPalace becomes genuinely optional rather than the only route
+  to meaning-based recall. Ollama remains a required local runtime for
+  embeddings, and `uv` is needed once to bootstrap the venv.
+- Declare a hard dependency on `local-rag` in `plugin.json` and `apm.yml`, so
+  installing `memory` deploys the retrieval engine on every host.
+- Generalize the provider layer behind a declarative `ProviderSpec`. The
+  projection, staging, atomic swap, projection marker, receipt, and backup
+  pruning path is now shared by every provider. MemPalace behavior is unchanged
+  and its test suite is the regression guard.
+- `search` under `rag` binds hits back to local records, returning review,
+  freshness, `source`, and `source_hash` with each result, and reports hits it
+  cannot bind in `unmatched_hits` instead of dropping them.
+- `search` degrades explicitly: when a provider is unreachable it falls back to
+  lexical local search annotated with `degraded_from`, `degraded_reason`, and
+  `degraded_detail`. Reconciliation is checked first, so a stale index refuses
+  rather than being masked by a quiet fallback.
+- `wake` reports `not-applicable` under `rag` without invoking the provider.
+- `doctor` verifies the local-rag runtime before probing the CLI and refuses
+  with the exact bootstrap command when the venv is missing or stale, closing
+  the gap on hosts that do not run Claude's `SessionStart` hook. `doctor
+  --bootstrap` builds it in place. The check applies only when the bundled
+  `bin/rag` launcher is in use; a user-supplied `CONTEXT_KIT_RAG_BIN` manages
+  its own runtime and is not gated.
+- Receipts now carry a provider-neutral `store_path`, and `provider` reflects
+  the configured provider. MemPalace receipts keep the `palace_path` key for
+  continuity. The `recovery_status` value `restored-to-live-palace` is now
+  `restored-to-live-store`.
+- `capture` and `archive-handoff` record provider receipts for any configured
+  provider, not only MemPalace.
+
+## 0.2.3 — 2026-08-04
+
+- Shorten the `memory-workflows` skill trigger to free aggregate discovery budget for the new
+  `token-economics` components. Scope and routing are unchanged; the removed
+  text was enumeration detail already covered in the skill body, and the
+  catalog budget stays at 4096 characters rather than being raised.
+
+## 0.2.2 — 2026-07-27
+
+- Shorten the discovery description(s) to free aggregate budget for the new
+  `corpus-review` components. Triggers and scope are unchanged; the catalog
+  budget is fixed, so every addition competes for the same remainder.
+
+## 0.2.1 — 2026-07-25
+
+- Adopt the evidence forms `verify` now defines for the `## Evidence` section,
+  so provenance stays citable across the `verify` → `context-handoff` → `memory`
+  chain. A bare command name is no longer an accepted source pointer; an
+  observed result needs its observation source — `command-id=<allowlist key>` or
+  `tool=<approved tool>@<target>` — plus an artifact pointer.
+
+## 0.2.0 — 2026-07-19
+
+- Add append-only review and freshness events over immutable memory records,
+  including sequenced replay, validated transitions, and stale-lock recovery.
+- Restrict active recall and provider projections to effective
+  `accepted/current` records while preserving inactive history for audit.
+- Add immutable provider receipts and guarded `sync-provider` dry-run/apply
+  reconciliation with staged project-isolated palaces, backups, and
+  live-palace projection markers.
+- Require explicit provider synchronization after eligible captures or state
+  changes; capture, handoff archival, and lifecycle hooks never mutate the
+  provider palace. Opt-in hooks queue payloads locally for explicit review.
+- Harden MemPalace compatibility checks against the tested 3.6.x CLI surface
+  and add an opt-in real-CLI smoke test.
+- Document project-scoped, server-enforced read-only GitHub Copilot MCP setup,
+  provider qualification criteria, and the design-only status of Memora.
+
+## 0.1.0 — 2026-07-19
+
+- Add the provider-neutral `context-kit/memory-v1` record contract.
+- Add capture, recall, review, and explicit handoff archival workflows.
+- Add a tested Python 3 standard-library adapter for a separately installed
+  MemPalace CLI with project-isolated storage and exact-argv execution.
+- Derive collision-resistant project storage keys and publish write-once records
+  atomically under concurrent capture.
+- Enforce project provenance, complete record and handoff structure, empty
+  allowlist boundaries, and local-only recall without MemPalace.
+- Add opt-in Claude Stop, PreCompact, and detached SessionEnd capture hooks.
+- Adopt Memora-inspired primary memories, cue anchors, freshness states,
+  supersession history, rank-fusion guidance, and propose-only consolidation.

memorykit-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Beacom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.