memware 0.1.1__tar.gz

memware-0.1.1/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "memware",
+  "owner": {
+    "name": "ericwalisko",
+    "url": "https://github.com/ericwalisko"
+  },
+  "description": "Memory for AI agents that only remembers the latest truth.",
+  "plugins": [
+    {
+      "name": "memware",
+      "source": "./integrations/claude-code",
+      "description": "Session transcripts indexed for recall; a belief ledger that only remembers the latest truth. Hooks: SessionEnd/PreCompact sync, prompt-time belief context.",
+      "version": "0.1.1",
+      "author": {
+        "name": "ericwalisko"
+      }
+    }
+  ]
+}

memware-0.1.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @ericwalisko

memware-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,21 @@
+name: Bug report
+description: Something behaves differently from what the docs say
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes: { label: memware version, placeholder: "memware --version" }
+    validations: { required: true }
+  - type: input
+    id: env
+    attributes: { label: Python and OS, placeholder: "3.12, macOS 15" }
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Commands or a short script using synthetic data. Never paste real transcripts.
+    validations: { required: true }
+  - type: textarea
+    id: expected
+    attributes: { label: Expected vs actual }
+    validations: { required: true }

memware-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/ericwalisko/memware/security/advisories/new
+    about: Report privately via GitHub security advisories.

memware-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,17 @@
+name: Feature request
+description: Propose a change
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes: { label: The problem this solves }
+    validations: { required: true }
+  - type: textarea
+    id: proposal
+    attributes: { label: Proposal }
+  - type: dropdown
+    id: readpath
+    attributes:
+      label: Does this add a model call to capture or recall?
+      options: ["No", "Yes, as an optional extra", "Yes, in the default path"]
+    validations: { required: true }

memware-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## What
+
+<!-- one or two sentences -->
+
+## Why
+
+<!-- the problem, with a link to the issue if there is one -->
+
+## Checklist
+
+- [ ] Tests added or updated (synthetic fixtures only)
+- [ ] `ruff check`, `ruff format --check`, `mypy`, `pytest` pass locally
+- [ ] Ledger semantics unchanged, or `docs/design.md` updated in this PR
+- [ ] Commits are signed off (`git commit -s`)

memware-0.1.1/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule: { interval: "monthly" }
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule: { interval: "monthly" }

memware-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip && pip install -e ".[dev,mcp]"
+      - run: ruff check src tests integrations
+      - run: ruff format --check src tests integrations
+      - run: mypy
+      - run: pytest --cov=memware --cov-report=term-missing
+      - run: python -m pip install build && python -m build

memware-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+# Publishing is authorized by a PyPI *trusted publisher* (OIDC): no API token is
+# stored anywhere. The binding on pypi.org names this repository, this workflow
+# file, and the `pypi` environment below — change any of the three and the
+# upload stops working. See RELEASING.md.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check --strict dist/*
+
+      - name: Install the wheel into a clean venv
+        # Core memware has no runtime dependencies, so this must resolve with the
+        # index switched off — anything else means a dependency leaked in.
+        run: |
+          python -m venv /tmp/verify
+          /tmp/verify/bin/pip install --no-index --find-links dist memware
+
+      - name: The console script reports the built version
+        run: |
+          version="$(/tmp/verify/bin/memware --version)"
+          echo "built version: ${version}"
+          if [ "${GITHUB_REF_TYPE}" = "tag" ] && [ "${GITHUB_REF_NAME#v}" != "${version}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match package version ${version}"
+            exit 1
+          fi
+
+      - name: The test suite passes against the installed wheel
+        # Imports resolve to site-packages, not src/ — this is what catches a
+        # subpackage or data file that never made it into the distribution.
+        run: |
+          /tmp/verify/bin/pip install pytest
+          /tmp/verify/bin/python -m pytest tests -q
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    # A manual run on a branch builds and verifies but never publishes.
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/memware
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

memware-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.db
+*.db-wal
+*.db-shm
+.memware/

memware-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files

memware-0.1.1/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- **Passage-level index.** Turns are split into ~300-500-token passages at ingest
+  (`memware.passage`), anchored by turn id and character offset, and FTS5 now indexes
+  passages instead of whole turns. Recall ranks passages, collapses to one hit per turn
+  and quotes only that turn's best matching passages (`passages_per_turn`, default 3);
+  `read_session` still returns whole turns. On a 24-question fact set this held accuracy
+  exactly (fact 24/24, stale 8/8, stale_rate 0) while halving the retrieved context,
+  30,403 -> 15,410 characters. The database is ~1.8x larger, since a passage stores its
+  own text.
+- Existing stores migrate on first open (`PRAGMA user_version` 0 -> 1): `turn_fts` is
+  dropped and every turn on disk is chunked, ~5 s for an 18k-turn corpus.
+- `memware-eval` reports the median retrieved context size per question.
+
+## [0.1.1] - 2026-09-03
+
+### Added
+- Multi-query recall: `memware recall Q1 Q2 …`, MCP `recall(queries=[…])`, Hermes `memware_recall(queries)` — phrasings fused by reciprocal rank so the calling agent supplies synonyms and expected values at call time.
+- Persistent skip list: `~/.memware/ignore-markers.txt` and `MEMWARE_IGNORE_MARKERS` — content markers every sync honours, so transcripts predating a marker or the no-capture flag are filtered by signature.
+- Evaluation guardrails: `MEMWARE_NO_CAPTURE=1` (hooks/provider/`sync --from-hook` no-op), `sync --skip-if-contains TEXT` / `--exclude GLOB`, `memware prune`, `memware-eval --corpus/--beliefs-from` clean-store builds, `memware.eval.MARKER`.
+- Hermes memory-provider plugin implementing the `MemoryProvider` ABC (prefetch, non-blocking sync_turn, session flush, built-in memory mirroring, four recall/remember tools); the repo is a Claude Code plugin marketplace (`claude plugin marketplace add ericwalisko/memware`).
+- `integrations/hermes/upstream/`: the Hermes provider packaged as hermes-agent's own `plugins/memory/<name>/` tree — lazy-installed dependency, profile-scoped store, `backup_paths()`, declarative desktop config schema — with tests in their layout, a docs entry draft, and a draft PR description in `docs/upstream-hermes-pr.md`. Prepared, not submitted.
+- Turn hits carry `snippet`: the FTS5 window around the matched terms (the head of a long turn often lacks the answer). Default window 96 tokens; `memware recall --snippet-tokens N`.
+- Release workflow that publishes to PyPI from a `v*` tag via trusted publishing
+  (OIDC, no stored token). It installs the built wheel into a clean venv and refuses
+  to upload when the tag and the package version disagree; `RELEASING.md` documents
+  the one-time pypi.org setup and the per-release steps.
+
+### Changed
+- Stale scoring is positional: an answer is stale only when the old value appears before the current one.
+- `memware-eval` mirrors the hook's subject gate for the beliefs context and reports the belief injection rate (overall and on negatives).
+- `memware-eval` now scores two contexts per question: `beliefs` (what a prompt-time hook injects) and `beliefs+turns`; negatives pass when the expected value is absent rather than when the context is empty.
+- The package version is read from `memware.__version__` by the build backend, so
+  `memware --version` and the published distribution cannot disagree.
+
+## [0.1.0] - 2026-09-02
+
+### Added
+- Bi-temporal belief ledger with deterministic `(subject, relation)` supersession,
+  event-time ordering, reinforcement, and reliability-gated review.
+- FTS5 transcript index with BM25 × activation ranking.
+- Ingest adapters for Claude Code session JSONL and generic message JSONL, with
+  idempotent byte-offset cursors.
+- `memware` CLI, optional MCP server, and retrieval-level evaluation runner.
+- `ReviewBackend` contract with JSONL and HTTP implementations.
+- Claude Code hook bundle and Hermes memory-provider skeleton.

memware-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,47 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance, race,
+caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse,
+inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include demonstrating
+empathy and kindness, being respectful of differing opinions, giving and gracefully
+accepting constructive feedback, accepting responsibility and apologizing to those
+affected by our mistakes, and focusing on what is best for the overall community.
+
+Examples of unacceptable behavior include sexualized language or imagery, trolling,
+insulting or derogatory comments, personal or political attacks, public or private
+harassment, publishing others' private information without explicit permission, and other
+conduct which could reasonably be considered inappropriate in a professional setting.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and will take
+appropriate and fair corrective action in response to any behavior they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an
+individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the
+maintainers through GitHub's private vulnerability reporting for this repository or by
+opening an issue marked confidential. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

memware-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for considering a contribution. Small, focused pull requests are easiest to review.
+
+## Development
+
+```bash
+git clone https://github.com/ericwalisko/memware && cd memware
+uv venv && uv pip install -e ".[dev,mcp]"     # or: python -m venv .venv && pip install -e ".[dev,mcp]"
+ruff check src tests && ruff format --check src tests
+mypy
+pytest
+```
+
+CI runs the same commands on Python 3.11, 3.12 and 3.13.
+
+## Ground rules
+
+- **Tests first.** Every behaviour change comes with a test that fails without it.
+  Fixtures are synthetic — never commit real transcripts or memories.
+- **The ledger semantics are a contract.** Changes to supersession ordering, policies,
+  or what `recall` may return need a design note in `docs/design.md` in the same PR.
+- **No model in the read path.** Proposals that add an LLM call to capture or recall
+  should be framed as optional, off-by-default extras.
+- Keep the core dependency-free. New runtime dependencies go behind an extra.
+
+## Releasing
+
+Maintainers only: [RELEASING.md](RELEASING.md) covers the one-time PyPI trusted-publisher
+setup and the per-release steps. Releases are cut from a `v*` tag; nothing is published
+by hand.
+
+## Sign-off (DCO)
+
+This project uses the [Developer Certificate of Origin](https://developercertificate.org/).
+Sign each commit with `git commit -s`, which adds `Signed-off-by: Your Name <email>`.
+No CLA.
+
+## Reporting bugs and proposing features
+
+Use the issue templates. For security issues, see [SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).

memware-0.1.1/LICENSE

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

memware-0.1.1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: memware
+Version: 0.1.1
+Summary: Memory for AI agents that only remembers the latest truth: a bi-temporal belief ledger plus a transcript index, in one SQLite file.
+Project-URL: Homepage, https://github.com/ericwalisko/memware
+Project-URL: Issues, https://github.com/ericwalisko/memware/issues
+Project-URL: Changelog, https://github.com/ericwalisko/memware/blob/main/CHANGELOG.md
+Author: ericwalisko
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-memory,bitemporal,claude-code,fts5,hermes,llm,mcp,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff==0.16.5; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# memware
+
+**Memory for AI agents that only remembers the latest truth.**
+
+memware is one SQLite file with two stores:
+
+- **turns** — immutable evidence. Every prompt and answer from past sessions,
+  split into ~400-token passages and indexed with FTS5. Recall ranks passages and
+  quotes only the matching ones; reading a session back returns whole turns.
+  BM25 × recency × use, no model in the loop.
+- **beliefs** — a bi-temporal ledger of facts. A new value for the same
+  `(subject, relation)` **supersedes** the old one. Recall only ever returns the
+  currently valid belief; history is kept for audit and never reaches a prompt.
+
+No daemon, no vector database, no LLM call at capture or read time. A 30-day
+corpus of a busy coding agent — 18k turns, 40k passages — indexes in about
+fourteen seconds into ~120 MB.
+
+```text
+$ memware sync ~/.claude/projects --harness claude-code
+{"added": 14348, "files": 1475}
+
+$ memware assert "api" "listens on port" "8443" --source "session 3f2a, turn 41"
+{"outcome": "superseded", "belief_id": 2, "incumbent_id": 1}
+
+$ memware recall "which port does the api use" --what beliefs
+api listens on port 8443            # 8080 is in the ledger, retired, and never surfaces
+```
+
+## Why
+
+Agent memory systems that rewrite what they remember degrade: continuous
+LLM consolidation can push utility *below* having no memory at all
+([Useful Memories Become Faulty When Continuously Updated by LLMs](https://arxiv.org/abs/2605.12978)).
+And embeddings cannot tell a *contradicted* fact from a *rephrased* one — AUROC 0.59 —
+so vector stores serve stale facts 15–40% of the time on evolving knowledge
+([Temporal Validity in Retrieval Memory](https://arxiv.org/abs/2606.26511)).
+
+memware borrows four mechanisms from human memory research and keeps them deliberately small:
+
+| mechanism | in the brain | in memware |
+|---|---|---|
+| evidence ≠ belief | hippocampus vs neocortex (complementary learning systems) | `turn` table is append-only; `belief` table is separate |
+| update on surprise | reconsolidation driven by prediction error | `memware assert` at the moment an agent notices a conflict |
+| only the latest understanding | reconsolidated traces overwrite in place | deterministic supersession keyed on `(subject, relation)`, ordered by **event time** |
+| need-probability recall | Anderson & Schooler 1991 / ACT-R activation | `bm25 × (1+age)^-d × (1 + w·ln(1+uses))` |
+
+Full rationale and citations: [docs/design.md](docs/design.md).
+
+## Install
+
+```bash
+pip install memware            # core, stdlib only (SQLite with FTS5)
+pip install "memware[mcp]"     # + MCP server
+```
+
+## Use it from Claude Code
+
+`integrations/claude-code/` is a Claude Code plugin (`claude plugin marketplace add
+ericwalisko/memware`, then `claude plugin install memware@memware`). Hooks: `SessionEnd`/`PreCompact` sync the
+transcript into the index; an optional `UserPromptSubmit` hook injects the handful of
+currently valid beliefs relevant to the prompt (beliefs only — transcript search is
+on demand through the MCP tools). See [docs/integrations.md](docs/integrations.md).
+
+## Use it from Hermes Agent
+
+`integrations/hermes/memware/` is a memory-provider plugin built on Hermes's
+`MemoryProvider` ABC — prompt-time belief prefetch, non-blocking turn capture, and
+`memware_recall` / `memware_remember` tools — sharing one store with Claude Code.
+
+## The supersession rule
+
+```text
+same key, same value   → reinforce (reliability rises, use is counted)
+same key, newer value  → supersede: incumbent gets valid_to = new.valid_from
+same key, older value  → filed as history; the timeline stays consistent
+weaker challenger      → parked as a candidate and sent to review
+```
+
+Ordering is decided by `valid_from` (when the evidence says it became true), never by
+insertion order — so a backfill converges to the same state in any order, twice, or in
+batches. Three policies: `auto` (last writer by event time), `gate_conflicts`
+(default: a less reliable challenger goes to review), `await_confirmation`.
+
+## Recall is keyword search; the agent supplies the meaning
+
+The index is FTS5/BM25 — fast, model-free, and literal. The `recall` tool therefore takes
+**several phrasings** and fuses them by reciprocal rank, so a tool-calling agent puts its
+own reasoning into retrieval at call time (synonyms, related concepts, the literal value it
+expects), the same way it would issue a few grep or web-search queries:
+
+```text
+recall(queries=["which port does the api listen on", "api port", "8443", "gateway listen port"])
+```
+
+Prompt-time injection (the hooks) stays deterministic and only injects beliefs whose
+*subject* the prompt names.
+
+## Keeping evaluations out of the evidence
+
+Headless runs write transcripts too. Set `MEMWARE_NO_CAPTURE=1` in any run you do not want
+indexed (hooks, the Hermes provider and `memware sync --from-hook` all honour it), put
+`[memware-eval]` in evaluation prompts, and use `memware-eval --corpus ROOT --db scratch.db
+--beliefs-from ~/.memware/memware.db` to judge retrieval against a store that excludes them.
+`memware prune --containing TEXT` un-indexes runs that already slipped in. For a durable filter that every sync honours — including runs that predate a marker — list content signatures in `~/.memware/ignore-markers.txt` (or `MEMWARE_IGNORE_MARKERS`); any transcript whose head contains one is never indexed.
+
+## Reviewing contested supersessions
+
+memware does not ship a UI. It ships a contract — `ReviewBackend` with `publish()` and
+`collect()` — plus two implementations: JSONL outbox/inbox files and a plain HTTP
+endpoint. Wire it to whatever you already use to make decisions.
+
+```bash
+memware review sync                       # outbox ~/.memware/review-outbox.jsonl
+echo '{"review_id": 7, "decision": "approve"}' >> ~/.memware/review-inbox.jsonl
+memware review sync                       # applied
+```
+
+## Evaluation
+
+`memware-eval` scores retrieval against a question set: does the right evidence
+surface, and does the stale value stay hidden? It needs no model, so results are
+reproducible. The protocol for end-to-end comparisons — agent alone vs agent + memware —
+is in [docs/eval.md](docs/eval.md).
+
+## Status
+
+Alpha. The schema may change before 1.0; the ledger semantics will not.
+
+## License
+
+MIT. See [LICENSE](LICENSE).