project-memory-mcp 0.5.0b1__tar.gz

project_memory_mcp-0.5.0b1/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+results/
+.memory/
+.codex/
+*.sqlite*
+*.db*
+*.jsonl
+*.mcpb
+*.zip
+*.whl
+*.tar.gz
+.DS_Store
+.env
+.env.*
+memory-viewer.html
+uv.lock
+example-run/
+node_modules/

project_memory_mcp-0.5.0b1/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.5.0b1
+
+First public beta of Project Memory. Adds an installable package, stable CLI, project setup and removal, an installed-process doctor, versioned launch configuration, a Codex plugin and public release checks. Project direction can change through explicit, evidenced revisions while retaining original requirements and flagging earlier dependent decisions for review.
+
+Preserves the local SQLite core, three-tool MCP interface, mechanical Codex capture, interruption reconciliation, Markdown snapshots, bounded retrieval, separate subjects and offline HTML viewer from the private 0.4 evaluation.
+
+The release does not claim universal client compatibility, guaranteed productivity gains or complete model inputs below 10K tokens. Those remain evaluation work.

project_memory_mcp-0.5.0b1/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Keep the runtime in Python's standard library unless a measured defect requires a dependency. Preserve immutable history, explicit acceptance, source provenance, subject boundaries and whole-record retrieval. Use ordinary professional sentences for record explanations and interface copy.
+
+Run the commands in the README before opening a pull request. Include a reproduction of the original defect, the changed behaviour and the relevant result. For performance claims, use comparable tasks with equal quality checks and report complete model inputs separately from retrieved characters. Count failed attempts and abandoned tasks; do not improve a ratio by excluding difficult work.
+
+Examples and public evidence must be synthetic. Never commit project databases, personal paths, configuration, transcripts or private source documents. Propose schema changes with a tested migration and backup path. Do not rewrite previously recorded decisions to match a newer interpretation.
+
+Use GitHub issues for reproducible defects and discussions about proposed changes. Maintainers are the Dankaro-projects repository owners. Beta feedback should describe installation success, completed work, preserved constraints, repeated research, corrections and time spent maintaining memory; omit project content unless it is deliberately shareable.

project_memory_mcp-0.5.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dankaro
+
+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.

project_memory_mcp-0.5.0b1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: project-memory-mcp
+Version: 0.5.0b1
+Summary: Local project memory for decisions, evidence and outcomes, with bounded MCP retrieval.
+Project-URL: Homepage, https://github.com/Dankaro-projects/project-memory
+Project-URL: Repository, https://github.com/Dankaro-projects/project-memory
+Project-URL: Issues, https://github.com/Dankaro-projects/project-memory/issues
+Author: Dankaro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codex,decisions,mcp,memory,sqlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Project Memory
+
+Project Memory keeps a project's decisions, evidence, outcomes and reviewed lessons in a local SQLite database. An AI assistant retrieves the relevant records through three MCP tools; people inspect the same history in a self-contained HTML viewer.
+
+Use it when a project repeatedly revisits research, loses the reasons behind decisions, or carries outdated requirements into new work. It preserves the original evidence and the conditions under which a decision or lesson applies.
+
+**Public beta.** The runtime uses Python 3.11+ and its standard library. There is no model service, vector database, telemetry or background maintenance process. The assistant still interprets evidence and needs explicit agreement before accepting a lesson or changing project requirements. [Evidence and limits](docs/evidence.md) describe what has actually been measured.
+
+<!-- mcp-name: io.github.Dankaro-projects/project-memory -->
+
+## Install and connect
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run this **inside the project you want to remember**:
+
+```sh
+uvx project-memory-mcp@0.5.0b1 setup --client codex --trust
+```
+
+This creates `.memory/project.sqlite`, adds a project-local MCP connection and nine command hooks, and asks the installed Codex host for the exact hook hashes to enable. Existing settings and records are preserved. Open a new Codex task afterwards. `--trust` explicitly enables these project hooks; omit it to review and enable them in Codex yourself.
+
+For a permanent CLI installation:
+
+```sh
+uv tool install project-memory-mcp==0.5.0b1
+project-memory doctor
+project-memory view
+```
+
+For another local MCP client, run `project-memory setup --client mcp`, then configure the client to run `project-memory serve --project /absolute/path/to/project`. Generic MCP supports explicit records and retrieval; Codex's automatic receipts are a separately verified integration. [Setup and lifecycle](docs/setup.md) includes imports, upgrades, backup, uninstall and client configuration.
+
+The same versioned wheel is available from [GitHub Releases](https://github.com/Dankaro-projects/project-memory/releases). The MCPB asset supports directory selection in compatible desktop clients.
+
+![The HTML viewer shows synthetic decisions, evidence, corrections and review status.](https://raw.githubusercontent.com/Dankaro-projects/project-memory/main/docs/images/viewer.png)
+
+## Use it in ordinary work
+
+Ask your assistant:
+
+> Capture VISION.md and our decision log. Show which statements are evidence, proposals and agreed requirements. Preserve the originals. Before choosing an approach, retrieve relevant decisions and check whether their evidence is still current.
+
+Then work normally. The assistant supplies record IDs and versions. You review the meaning, rather than maintain a second set of forms.
+
+- A decision records its evidence, initial choice, alternatives, uncertainty, expected consequences and conditions for reconsideration.
+- Actions and actual outcomes attach to that decision. Revisions retain the earlier choice and its result.
+- Successful practices, anti-patterns and recoveries can become proposed lessons. A separate review accepts, rejects or retires them, with their scope and exceptions intact.
+- Code reviews, writing corrections and research remain separate subjects. A dependency across subjects must name the evidence and explain why it matters.
+- Selected Markdown files are captured verbatim. Changed, missing and superseded evidence is flagged. Importing a vision does not approve its proposals.
+- Approved project requirements can evolve through append-only revisions. Earlier decisions retain the version they used and become reviewable when the agreed basis changes.
+
+Run `project-memory view` for decisions, documents, corrections, patterns, drift, captures and unresolved work. It creates a fresh, offline HTML snapshot with evidence navigation. Source bodies are excluded unless you add `--include-bodies`.
+
+## What is automatic
+
+Codex hooks mechanically record session and tool events, sizes, hashes and available execution metadata. They do not turn a failed command into a lesson or assume that an interrupted command rolled back. The assistant records interpretation separately and checks side effects before retrying uncertain work.
+
+Retrieval returns bounded, complete records and preserves exceptions. Search indexes and explicit source slices support expansion when needed. The default MCP reply limit is 6,000 characters, with an explicit maximum of 20,000; these are **characters in the tool result, not complete model-input tokens**. Keeping every model input below 10K tokens remains a target, subordinate to quality and feature preservation.
+
+## Develop and verify
+
+```sh
+python -m unittest discover -s tests -q
+python -m examples.document_case --output results/documents
+python -m examples.host_example --output results/host-example
+node tests/viewer_logic.cjs
+uv build
+python scripts/check_artifacts.py dist
+python scripts/installed_smoke.py dist
+```
+
+The public artifacts contain code, documentation and synthetic examples. They exclude project databases, host transcripts, private evaluation archives and local configuration. [Contributing](CONTRIBUTING.md), [security](SECURITY.md), [record fields](docs/record-fields.md), [release process](docs/releasing.md).

project_memory_mcp-0.5.0b1/README.md

@@ -0,0 +1,70 @@
+# Project Memory
+
+Project Memory keeps a project's decisions, evidence, outcomes and reviewed lessons in a local SQLite database. An AI assistant retrieves the relevant records through three MCP tools; people inspect the same history in a self-contained HTML viewer.
+
+Use it when a project repeatedly revisits research, loses the reasons behind decisions, or carries outdated requirements into new work. It preserves the original evidence and the conditions under which a decision or lesson applies.
+
+**Public beta.** The runtime uses Python 3.11+ and its standard library. There is no model service, vector database, telemetry or background maintenance process. The assistant still interprets evidence and needs explicit agreement before accepting a lesson or changing project requirements. [Evidence and limits](docs/evidence.md) describe what has actually been measured.
+
+<!-- mcp-name: io.github.Dankaro-projects/project-memory -->
+
+## Install and connect
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run this **inside the project you want to remember**:
+
+```sh
+uvx project-memory-mcp@0.5.0b1 setup --client codex --trust
+```
+
+This creates `.memory/project.sqlite`, adds a project-local MCP connection and nine command hooks, and asks the installed Codex host for the exact hook hashes to enable. Existing settings and records are preserved. Open a new Codex task afterwards. `--trust` explicitly enables these project hooks; omit it to review and enable them in Codex yourself.
+
+For a permanent CLI installation:
+
+```sh
+uv tool install project-memory-mcp==0.5.0b1
+project-memory doctor
+project-memory view
+```
+
+For another local MCP client, run `project-memory setup --client mcp`, then configure the client to run `project-memory serve --project /absolute/path/to/project`. Generic MCP supports explicit records and retrieval; Codex's automatic receipts are a separately verified integration. [Setup and lifecycle](docs/setup.md) includes imports, upgrades, backup, uninstall and client configuration.
+
+The same versioned wheel is available from [GitHub Releases](https://github.com/Dankaro-projects/project-memory/releases). The MCPB asset supports directory selection in compatible desktop clients.
+
+![The HTML viewer shows synthetic decisions, evidence, corrections and review status.](https://raw.githubusercontent.com/Dankaro-projects/project-memory/main/docs/images/viewer.png)
+
+## Use it in ordinary work
+
+Ask your assistant:
+
+> Capture VISION.md and our decision log. Show which statements are evidence, proposals and agreed requirements. Preserve the originals. Before choosing an approach, retrieve relevant decisions and check whether their evidence is still current.
+
+Then work normally. The assistant supplies record IDs and versions. You review the meaning, rather than maintain a second set of forms.
+
+- A decision records its evidence, initial choice, alternatives, uncertainty, expected consequences and conditions for reconsideration.
+- Actions and actual outcomes attach to that decision. Revisions retain the earlier choice and its result.
+- Successful practices, anti-patterns and recoveries can become proposed lessons. A separate review accepts, rejects or retires them, with their scope and exceptions intact.
+- Code reviews, writing corrections and research remain separate subjects. A dependency across subjects must name the evidence and explain why it matters.
+- Selected Markdown files are captured verbatim. Changed, missing and superseded evidence is flagged. Importing a vision does not approve its proposals.
+- Approved project requirements can evolve through append-only revisions. Earlier decisions retain the version they used and become reviewable when the agreed basis changes.
+
+Run `project-memory view` for decisions, documents, corrections, patterns, drift, captures and unresolved work. It creates a fresh, offline HTML snapshot with evidence navigation. Source bodies are excluded unless you add `--include-bodies`.
+
+## What is automatic
+
+Codex hooks mechanically record session and tool events, sizes, hashes and available execution metadata. They do not turn a failed command into a lesson or assume that an interrupted command rolled back. The assistant records interpretation separately and checks side effects before retrying uncertain work.
+
+Retrieval returns bounded, complete records and preserves exceptions. Search indexes and explicit source slices support expansion when needed. The default MCP reply limit is 6,000 characters, with an explicit maximum of 20,000; these are **characters in the tool result, not complete model-input tokens**. Keeping every model input below 10K tokens remains a target, subordinate to quality and feature preservation.
+
+## Develop and verify
+
+```sh
+python -m unittest discover -s tests -q
+python -m examples.document_case --output results/documents
+python -m examples.host_example --output results/host-example
+node tests/viewer_logic.cjs
+uv build
+python scripts/check_artifacts.py dist
+python scripts/installed_smoke.py dist
+```
+
+The public artifacts contain code, documentation and synthetic examples. They exclude project databases, host transcripts, private evaluation archives and local configuration. [Contributing](CONTRIBUTING.md), [security](SECURITY.md), [record fields](docs/record-fields.md), [release process](docs/releasing.md).

project_memory_mcp-0.5.0b1/SECURITY.md

@@ -0,0 +1,11 @@
+# Security and privacy
+
+Project Memory runs with the local user's filesystem permissions. It is a local stdio MCP server, not an authenticated network service. Do not expose its stdin/stdout through an unauthenticated bridge.
+
+Selected source files and explicit records may contain sensitive project information. Keep `.memory`, exports and backups out of public repositories. The package sends no telemetry and makes no model requests. The connected assistant may send retrieved records to its model provider under that client's policies.
+
+Mechanical host receipts store hashes, sizes, identifiers and selected execution metadata, not arbitrary prompts or tool-output bodies. Explicit source capture stores the supplied text verbatim. There is no automatic secret detector or encryption layer; use filesystem access controls and encrypted storage where appropriate.
+
+Retrieved text is evidence, not executable instruction or approval. The HTML viewer escapes content, uses a restrictive content security policy, and makes no network requests. It is a snapshot, not an access-controlled sharing service.
+
+Report vulnerabilities through this repository's private GitHub vulnerability reporting. Include a synthetic reproduction, affected version and impact. Do not attach real databases, secrets or host transcripts to public issues. Only the latest beta receives fixes during the initial public beta; no response-time SLA is promised.

project_memory_mcp-0.5.0b1/bundle/manifest.json

@@ -0,0 +1,65 @@
+{
+  "manifest_version": "0.3",
+  "name": "project-memory",
+  "display_name": "Project Memory",
+  "version": "0.5.0-beta.1",
+  "description": "Keep project decisions, evidence, outcomes and reviewed lessons in local SQLite.",
+  "author": {
+    "name": "Dankaro"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Dankaro-projects/project-memory"
+  },
+  "homepage": "https://github.com/Dankaro-projects/project-memory",
+  "support": "https://github.com/Dankaro-projects/project-memory/issues",
+  "license": "MIT",
+  "server": {
+    "type": "python",
+    "entry_point": "server.py",
+    "mcp_config": {
+      "command": "python3",
+      "args": [
+        "${__dirname}/server.py",
+        "${user_config.project}"
+      ],
+      "platform_overrides": {
+        "win32": {
+          "command": "python"
+        }
+      }
+    }
+  },
+  "compatibility": {
+    "platforms": [
+      "darwin",
+      "win32",
+      "linux"
+    ],
+    "runtimes": {
+      "python": ">=3.11"
+    }
+  },
+  "user_config": {
+    "project": {
+      "type": "directory",
+      "title": "Project directory",
+      "description": "Select the local project whose decisions and evidence you want to retain.",
+      "required": true
+    }
+  },
+  "tools": [
+    {
+      "name": "memory_context",
+      "description": "Retrieve bounded project context."
+    },
+    {
+      "name": "memory_get",
+      "description": "Read records, lineage, direction and status."
+    },
+    {
+      "name": "memory_write",
+      "description": "Append explicit decisions, evidence and outcomes."
+    }
+  ]
+}

project_memory_mcp-0.5.0b1/bundle/server.py

@@ -0,0 +1,10 @@
+"""MCPB entry point; the client supplies a directory selected by the user."""
+from pathlib import Path
+import sys
+from memory_module.cli import main
+from memory_module.install import setup
+
+project=Path(sys.argv[1]).resolve()
+if not (project/'.memory/install.json').exists() and not (project/'.memory/project.sqlite').exists():
+    setup(project,client='mcp')
+raise SystemExit(main(['serve','--project',str(project)]))

project_memory_mcp-0.5.0b1/docs/evidence.md

@@ -0,0 +1,75 @@
+# Evidence and limits
+
+The public beta preserves a working private prototype and adds installation, lifecycle management and approved project revisions. Measurements below distinguish deterministic checks, real host execution and untested product hypotheses. A passing suite alone does not establish day-to-day productivity.
+
+## Reproducible beta checks
+
+Run the commands in the README in a fresh checkout. Each example output directory must be new. Outputs stay under the ignored `results` directory.
+
+| Check | Observed locally on 13 September 2026 | Meaning |
+|---|---|---|
+| Python regression and lifecycle suite | 101 tests passed | Covers immutable history, boundaries, retries, stale evidence, revision approval, interrupted setup recovery and preservation of existing settings. |
+| Fresh wheel installation outside the checkout | Passed | CLI, repeated capture, a separate MCP process, packaged viewer, backup and removal operate without the source directory. |
+| Scripted document/retrieval case | 7/7 checks passed | An oversized lesson remains discoverable, exceptions survive expansion, changed files flag decisions, unchanged captures reuse a version and original text is reconstructed. |
+| Complete source expansion at a 2,500-character reply limit | 2 calls; 4,338 returned characters in this run | Path length affects envelope size. These are reply characters, not model tokens. |
+| Actual parser failure and recovery | Exit 1, then exit 0 | The example retains both outcomes and one unresolved action. It does not infer a semantic lesson from an exit code. |
+| Chrome 152 HTML execution | Passed, zero network requests and JavaScript errors | Covers navigation, filters, paging, escaped content, source freshness, correction ordering and mobile width. |
+
+`tests/test_product.py` injects a write interruption before and after the hook configuration write, retries setup and checks for duplicate hooks and lost unrelated settings. It also aborts approval inside a transaction and verifies that neither the revision nor its table creation leaks through a partial commit.
+
+The wheel has zero declared runtime dependencies. Build tools, the optional Playwright browser check and live Codex verification are development dependencies. Package sizes and hashes are emitted by `scripts/check_artifacts.py`; release assets provide the exact published bytes.
+
+## Installed Codex beta boundary
+
+The installed wheel ran in a separate virtual environment and project directory with Codex 0.153.4 on macOS. The setup command persisted project trust and obtained nine exact hashes from the actual host. Fresh sessions observed all nine lifecycle events, including `SessionEnd` on ordinary CLI shutdown. The verification client no longer supplies temporary project trust. App-server unsubscribe does not itself emit `SessionEnd` on this host.
+
+An interruption case wrote one marker, interrupted the tool, then resumed the same task through a new host process. The marker remained exactly once; an unconfirmed execution receipt and unknown process completion remained visible. Seven recovery MCP calls completed without a reported error. Compaction preserved all four checked facts, including the legacy exception and unmeasured production outcome. No adapter calls were recursively captured as external work.
+
+A separate document task passed all twelve quality and integration checks. It used five MCP calls, including one rejected relative document path followed by a successful absolute-path retry. Stating the absolute-path requirement in the tool schema did not eliminate this model correction. Raw model outputs and host transcripts remain local; the reviewed [aggregate report](verification-0.5.0b1.json) contains counts and provider usage.
+
+| Comparable synthetic case | Before fixes | After fixes | Quality |
+|---|---:|---:|---|
+| Document task: aggregate provider input | 116,481 | 114,403 | 12/12 checks in both; one path correction in each. |
+| Interruption and recovery: aggregate provider input | 259,684 | 289,216 | The side effect occurs once and unknown execution remains visible in both. |
+
+These are single runs of the same harness and model, not a controlled productivity study. Path lengths and model choices vary. The integration fixes improve capture correctness; the recovery rerun uses more tokens. Neither result establishes a general saving. Human corrections and maintenance minutes were not measured.
+
+To reproduce the live boundary after installing the release, create an empty test directory, set `TEST_PROJECT` to its absolute path, and run these commands from the checkout. Each output directory must be new. The harness uses the signed-in Codex account and consumes model usage.
+
+```sh
+project-memory setup --project "$TEST_PROJECT" --db "$TEST_PROJECT/memory.sqlite" --client codex --trust
+python -m examples.codex_interrupt --project "$TEST_PROJECT" --output results/live-interruption
+python -m examples.codex_documents --project "$TEST_PROJECT" --output results/live-documents
+python -m examples.codex_lifecycle --project "$TEST_PROJECT" --output results/live-lifecycle
+codex exec -C "$TEST_PROJECT" --skip-git-repo-check 'Reply only: The session can close.'
+project-memory doctor --project "$TEST_PROJECT"
+python -m examples.context_audit results/live-interruption
+```
+
+The context audit exits with status 1 when the target is not met. That failure is evidence, not a reason to remove conditions or skip difficult tasks.
+
+## Prior prototype measurements
+
+The following are historical results from the private prototype, not a new public-beta trial. The private databases and host transcripts are intentionally excluded from this repository.
+
+Three synthetic paired Codex tasks preserved ten quality checks and reduced aggregate provider input from 93,435 to 74,634 tokens, a 20.1% reduction. Repeated reads of current research fell from two to zero; the necessary stale-source refresh remained one in each condition. A different MCP-first approach increased input from 93,895 to 163,369 tokens because it added model turns. Neither experiment establishes general savings.
+
+A later document workflow passed twelve integration and answer checks, with five MCP calls: four succeeded, one exceeded the allowed reply limit and was corrected. Its complete inputs ranged from 14,556 to 17,721 tokens. There was no matched control. An early result parser missed that error because it relied on a missing host flag; the evaluator was corrected to inspect returned error content. Errors must remain in the reported denominator.
+
+The earlier host verification observed all nine Codex lifecycle events, a real interrupted command, and recovery through a new host process. The command's marker remained exactly once. Process completion remained unknown where the evidence could not establish it. Fault injection before SQLite capture blocked an action; a post-capture failure preserved its side effect and exposed an unconfirmed receipt. These observations motivate the public harnesses, not a claim that every host version behaves identically.
+
+## Public packaging defects found and corrected
+
+The initial Windows run exposed a real freshness defect: a captured `file:///D:/...` URI was not converted back to a Windows path, so changed or unreadable documents appeared current. The implementation now uses the standard library's platform-aware URL-to-path conversion. The same existing cases are rerun on Windows rather than skipped.
+
+The first bundle manifest used an unsupported platform key. The official MCPB validator rejected it; the manifest now uses the documented `platform_overrides` field and passes validation.
+
+Fresh host execution exposed two further defects. Setup had trusted hook hashes while leaving project trust effective only within its temporary host process. Setup now writes persistent trust before obtaining the hashes and verifies the saved setting. The renamed adapter also recorded its own MCP calls; capture now excludes both the legacy and public adapter namespaces. Comparable cases were rerun after both fixes. The browser report now lists optional project-view checks only when their fixture actually ran.
+
+## What remains unmeasured
+
+Daily completion rates, human corrections, net maintenance time, long-term drift and competing products have not been measured in a representative public beta. No guarantee of autonomous learning or competitor superiority follows from the current evidence. The assistant can overlook evidence, write a poor interpretation or fail to record a dependency. Textual freshness cannot establish whether an unchanged vision is still the right vision.
+
+Below 10K tokens in every complete model input remains an unmet target. Mandatory context, tool definitions and accumulated host history can exceed it before memory retrieval. Do not remove features, exceptions or evidence to meet the target. Measure the complete input as reported by the provider; label character-based estimates separately.
+
+A useful beta trial includes difficult work and failures as well as successes. For each comparable task, record completion, acceptance checks, provider input tokens, repeated research, corrections and minutes spent maintaining memory. Record unknown measurements as unknown. No participant content or telemetry is collected automatically.

project_memory_mcp-0.5.0b1/docs/record-fields.md

@@ -0,0 +1,37 @@
+# Record fields
+
+All event payloads reject unknown fields. Text must be nonempty; lists and costs have type and size checks. Dates require an explicit time zone and are normalized to UTC.
+
+| Kind | Required payload | Optional payload |
+|---|---|---|
+| decision | decision, why, expected, reconsider_when | uncertainty, assumptions, alternatives, review_after, follow_up_owner, model, condition, case_id |
+| action | action | host_reference |
+| action_result | execution_status, summary | duration_ms, artifact |
+| outcome | observed, assessment, assessment_reason, severity, attribution | tokens, human_corrections, duration_ms, failure_type, model, completion, context_characters, research_calls, repeated_research, maintenance_ms |
+| review | target, revision, summary, findings | None |
+| correction | before, after, reason, scope | None |
+| research | question, findings, gaps | queries, refresh_reason |
+| lesson | when, do, because, exceptions | pattern_type |
+| lesson_review | lesson_id, status, reason | None |
+| follow_up | review_after, owner, reason | None |
+| episode_status | status, reason | None |
+| note | text | None |
+
+`assumptions`, `alternatives` and `queries` are lists of strings. Review `findings` is a list of objects with exactly `location`, `issue` and `severity`. An empty findings list represents a completed review without findings, not proof that the code is correct. Record the exact code revision in `revision` and attach the captured code or review output as evidence.
+
+Outcome assessments are `pending`, `unknown`, `good`, `bad`. Severity is `none`, `minor`, `major`, `unknown`; review finding severity excludes `none`. Execution status is `completed`, `failed`, `unknown`. Lesson review status is `accepted`, `rejected`, `retired`. Episode status transitions are active/reopened to settled/abandoned, and settled/abandoned to reopened.
+
+Code reviews, explicit corrections and lesson reviews require evidence. Good/bad outcomes require evidence and a preceding action. Scoped lessons require evidence; legacy general lessons remain compatible. A lesson review must explicitly link its lesson. Hook decisions additionally require a follow-up owner and date.
+
+Sources take `source_key`, `title`, `summary`, `body`, `origin`, optional `review_after`, and `subject` (default general). Origin is `user`, `tool` or `document`. The source key identifies a logical source; versions are assigned automatically and content is hashed. A source key cannot change subject.
+
+Checks validate structure and references, not whether the source proves the claim. Genuine missing information should be described as missing, not filled with invented evidence.
+
+Codex decision capture additionally requires evidence, uncertainty and an alternatives list. Empty alternatives explicitly records that none were considered. Writing corrections submitted through capture belong to writing episodes. All capture triggers require evidence, including research. The low-level API remains compatible with older records.
+
+`completion` is `complete`, `partial`, `blocked` or `abandoned`. `pattern_type` is `practice`, `anti_pattern` or `recovery`. Numeric effort fields are nonnegative integer measurements; omit unmeasured values. `tokens` is caller-reported and must identify its meaning in the evidence. The live evaluator uses Codex's reported cumulative input/output usage and keeps automated rubric corrections separate from human corrections.
+# Record wording
+
+New explanatory fields use complete sentences with a named actor or object and a verb. For example, write “This correction applies to claims about features that have not been evaluated.” instead of “Claims about untested features.” A current rule uses present tense; an observed outcome uses the tense of the observation. An expected consequence remains explicitly conditional. Short titles and status values remain labels.
+
+The module validates required fields and their types mechanically. It does not guess whether prose is true, grammatical or acceptable. A reviewer checks meaning, scope, evidence and exceptions explicitly. Original quotations and historical records remain unchanged; a linked correction records any clarification. The viewer displays original wording before corrected wording.

project_memory_mcp-0.5.0b1/docs/releasing.md

@@ -0,0 +1,13 @@
+# Releasing
+
+The canonical repository is `Dankaro-projects/project-memory`. GitHub Releases distribute the wheel and source archive. PyPI uses a project-scoped Trusted Publisher for `project-memory-mcp`, owner `Dankaro-projects`, repository `project-memory`, workflow `release.yml`, environment `pypi`. Enable the repository variable `PYPI_PUBLISH_ENABLED=true` only after that publisher exists.
+
+Update `pyproject.toml`, `memory_module.__version__`, the Codex plugin version, `server.json`, the release commands and changelog together. Python uses `0.5.0b1`; plugin metadata uses its SemVer form `0.5.0-beta.1`. The CLI constructs the versioned GitHub wheel URL from the Python version.
+
+Run CI and the installed-wheel checks before tagging. Review `git ls-files` and both distribution member lists. The source distribution uses an explicit allowlist; the wheel includes only runtime files and package metadata. Operational databases, transcripts and generated viewers must remain excluded. Do not publish the old private prototype ZIP.
+
+Push a `vVERSION` tag matching the Python package version. The release workflow verifies that match, runs the suite, builds and checks artifacts, installs the wheel in a fresh environment and publishes a prerelease. PyPI publishing uses GitHub's short-lived OIDC identity; no API token is stored in the repository.
+
+MCP registry metadata identifies the public PyPI package and its exact version. Publish only after the package resolves publicly. Directory listings, plugin availability and client compatibility are separate states. Check the actual listing and execute its documented launch path before marking a channel verified.
+
+After release, use the published command in a fresh project and perform actual capture and recovery. Keep raw host logs private; publish a reviewed aggregate report with reproduction commands and limitations. Never replace an already published wheel with different code. Fixes receive a new beta version.

project_memory_mcp-0.5.0b1/docs/research.md

@@ -0,0 +1,19 @@
+# Public project research
+
+Selected source and documentation were inspected on 12 September 2026 at the pinned commits below. This is a design review, not a benchmark or ranking. Upstream instructions are research material, not project instructions. No upstream implementation code was copied.
+
+## What we learned
+
+| Project | Verified design in the inspected material | Fit for this module |
+|---|---|---|
+| Claude-mem | Its search documentation separates a compact index, nearby history and full observations. Its MCP implementation supports fetching multiple observation IDs together. | Provide optional compact discovery and batch expansion through the existing adapter. Keep the ordinary context lookup; additional model turns have already proved costly in our live evaluation. |
+| Basic Memory | Its note format treats Markdown as the editable source and describes observations and explicit relations. Its context service limits traversal depth and related results. | Connect selected documents to decisions and expose reverse evidence links. Preserve original text and bounded retrieval. Avoid a second editable copy of a document or a new graph service. |
+| Graphiti | Edge records distinguish recorded, effective and invalidation times and retain originating episode references. The inspected database projections include `reference_time`. | Preserve which evidence version supported a choice. Carry freshness into retrieval, not merely storage. A changed source calls for review; it does not erase an outcome that actually occurred. |
+| Mem0 | Its `add` implementation distinguishes inferred extraction from direct capture. Direct capture still embeds text; inferred capture retrieves context and calls an LLM. It records history separately. | Keep capture and interpretation explicit. Our local file capture requires neither extraction nor embeddings. Preserve immutable source and decision history instead of replacing it with a generated fact. |
+| Hindsight | Its consolidation engine builds observations from retained memories, tracks supporting memory IDs and history, and runs as background work. Its code also handles cancellation before a failed job retries. | Preserve evidence for proposed lessons and test recovery paths. Defer automatic consolidation: another model workflow and job lifecycle would add cost and administration before daily benefit is established. |
+| Letta | The former repository points to the current `letta-code` repository. Its local memory prompt describes a small resident context and external files, with committed changes taking effect on later compilation. Its local context UI estimates stored-message tokens from characters. | Keep a small working context and inspect details on demand. Do not confuse an estimate with provider-measured complete input, or assume changing a memory immediately changes an active model turn. |
+
+Sources: [Claude-mem search design](https://github.com/thedotmack/claude-mem/blob/b11034b6eb406ac0f27fcaf5a013eeef580bad66/docs/public/usage/search-tools.mdx) and [MCP implementation](https://github.com/thedotmack/claude-mem/blob/b11034b6eb406ac0f27fcaf5a013eeef580bad66/src/servers/mcp-server.ts); [Basic Memory note format](https://github.com/basicmachines-co/basic-memory/blob/b04d1b6d8590ed23f5838ee2d2ca2a8c3358c209/NOTE-FORMAT.md) and [context service](https://github.com/basicmachines-co/basic-memory/blob/b04d1b6d8590ed23f5838ee2d2ca2a8c3358c209/src/basic_memory/services/context_service.py); [Graphiti edge model](https://github.com/getzep/graphiti/blob/c035afb7990b6077331a81e98b04efcfd9bf8184/graphiti_core/edges.py) and [database projections](https://github.com/getzep/graphiti/blob/c035afb7990b6077331a81e98b04efcfd9bf8184/graphiti_core/models/edges/edge_db_queries.py); [Mem0 capture implementation](https://github.com/mem0ai/mem0/blob/c7ee362aff94a369af70f13f2b4f853f6793ff4c/mem0/memory/main.py); [Hindsight consolidation](https://github.com/vectorize-io/hindsight/blob/bde55237f53bf55aacd048b01e29d7dc23b83a85/hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py); [Letta context documentation](https://github.com/letta-ai/letta-code/blob/9a40d271f8ff77a3f84e4544645c6226faab0dab/src/agent/prompts/letta_local_memfs.md) and [context estimates](https://github.com/letta-ai/letta-code/blob/9a40d271f8ff77a3f84e4544645c6226faab0dab/src/web/local-memory-context.ts).
+
+
+The module adopted compact discovery, batch expansion, exact Markdown capture and reverse evidence links while retaining SQLite and zero runtime dependencies. Project Memory separately adds explicit requirement revisions. It does not add automatic model consolidation or a graph service. See [evidence](evidence.md) for measured results and limits.

project_memory_mcp-0.5.0b1/docs/setup.md

@@ -0,0 +1,67 @@
+# Setup and lifecycle
+
+Run commands inside the intended project or pass `--project /absolute/path`. A missing database is created only by `setup`; `serve`, `doctor` and `view` refuse a missing database rather than silently create an empty project.
+
+## Select existing documents
+
+```sh
+project-memory setup --client codex --trust --document VISION.md --document DECISIONS.md
+```
+
+Repeated setup does not duplicate hooks or unchanged source versions. Source documents remain in place. If the project has no agreed requirements, setup stores an explicit statement that none have been approved. You can supply already agreed text using repeated `--requirement` arguments. Changing existing requirements requires a separate, evidenced approval, not a setup flag.
+
+The assistant can capture another selected file using `memory_write document`. It should use `memory_get direction` before an explicitly authorised `approve_requirements` operation. That operation requires complete requirement sentences, an approval reason, actor, evidence references and the current version. File capture and approval are different actions.
+
+## Generic MCP configuration
+
+After `project-memory setup --client mcp`, adapt this configuration to the client's documented MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "project_memory": {
+      "command": "project-memory",
+      "args": ["serve", "--project", "/absolute/path/to/project"]
+    }
+  }
+}
+```
+
+Use the absolute installed executable if the desktop client cannot find it on PATH. `PROJECT_MEMORY_PROJECT` can supply the project directory when a client supports environment configuration. There is no global active-project pointer. Cloud-only clients cannot reach a local stdio process.
+
+The Codex plugin provides the same three MCP tools and a short workflow skill. Install it from this repository's marketplace. If a project already has a setup-managed MCP connection, avoid enabling a second copy through the plugin. Hooks require project setup and host trust; plugin discovery alone does not enable capture.
+
+## Verify the connection
+
+`project-memory doctor` starts a separate installed MCP process, initialises it, lists tools and requests the decision schema. It also checks SQLite integrity and reports observed hook counts and unconfirmed actions. Missing lifecycle events may not have happened yet; existing receipt counts are historical evidence, not proof that today's host configuration still works.
+
+In a new Codex task, ask the assistant to capture a selected document, record a decision with evidence, perform a small project action and record its actual outcome. Inspect the records with `view` and `doctor`. Reproducible live interruption and lifecycle harnesses are in `examples/`; they require a signed-in local Codex and intentionally execute synthetic work. [Evidence](evidence.md) separates those checks from unit tests.
+
+## Back up, upgrade and remove
+
+```sh
+project-memory backup /absolute/path/to/backup.sqlite
+```
+
+The destination must be new. SQLite's backup API provides a consistent database copy. Setup also creates a backup of the database and existing Codex configuration on first connection. Keep backups on storage you control.
+
+Upgrade by installing the next published wheel using `uv tool install --force --from RELEASE_WHEEL_URL project-memory-mcp`, then rerun `project-memory setup --client codex --trust`. The recorded launcher is versioned; setup updates its configuration and verifies new host hashes. Run `doctor` and a new task after an upgrade. A configuration edit within the managed block produces a conflict rather than overwriting it.
+
+If setup is interrupted, repeat the same setup command. A small ownership file lets it finish after either configuration write. Uninstall after completing any pending setup:
+
+```sh
+project-memory uninstall
+uv tool uninstall project-memory-mcp
+```
+
+Uninstall removes only its project connection and exact hook commands. It preserves records, source documents, backups and other client configuration. Codex can retain inactive trust entries for removed commands. Setup never edits unrelated global MCP connectors.
+
+## Existing memory-module databases
+
+Back up the database first. If the old project already has the legacy `memory` MCP adapter and its command hooks, disable that connection before adding the public adapter so both versions do not capture the same work. The installer detects the legacy MCP entry and refuses to create a duplicate. Use `project-memory setup --db /absolute/path/to/existing.sqlite --client codex --trust` to explicitly connect it. Core history remains in SQLite schema 2; optional host and project-revision tables are additive. Original immutable requirements remain revision zero. Older versions do not understand revised requirements: after the first approved revision, use this version or newer; restore the pre-upgrade backup for a deliberate rollback.
+
+Do not copy an old private evidence ZIP into the public repository. `.memory` is private operational data, including generated HTML and backups.
+
+## Desktop bundle
+
+The GitHub release also provides an MCPB file. A compatible desktop client asks you to select a project directory and starts the bundled Python server. The directory picker replaces hand-edited MCP configuration. Python 3.11+ must be available to the client (`python3` on macOS/Linux, `python` on Windows). The bundle initialises an empty selected project when needed, with no approved project-specific requirements; it preserves an existing setup. It supports generic explicit capture, not Codex lifecycle hooks. The bundle entry point is tested independently; see the compatibility evidence before assuming support in a particular client.