agemem 0.1.0__tar.gz

agemem-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+.env.*
+.cache/
+vendor/
+runs/
+*.db
+
+.venv-*/
+.agemem/local/
+
+# Maintainer workspace (keep local copies, exclude from public source)
+/HANDOFF.md
+/memory/
+/experiments/
+
+# Local benchmark/probe output and findings
+/reports/
+
+# Python build and tool output
+/dist/
+/build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/

agemem-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.1.0] - 2026-10-26
+
+### Added
+
+- Initial 0.1.0 candidate: project-memory CLI and stdio MCP for recall, capture,
+  screened notes, indexing and maintenance.
+- Guided and unattended project setup, versioned private YAML configuration,
+  and MCP registration for Codex, Cursor and Claude Code.
+- Local read-only Claude Code/Codex hooks installed by default during project setup and explicit executable
+  launchers for testing unpublished source builds.
+- Local BM25/dense retrieval, optional adapted RAW-RAG retrieval, hosted Jev
+  decisions and optional GPU QSIV, ollaya and cascade providers.
+- Installation, agent guidance and PlantUML architecture/setup/recall diagrams.
+
+Experimental first release. Python 3.12–3.14; QSIV installation requires Linux x86_64
+and a compatible NVIDIA GPU. YAML schema version 1 accepts existing unversioned
+configuration. Database and configuration migrations remain explicit.

agemem-0.1.0/LICENSE

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

agemem-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: agemem
+Version: 0.1.0
+Summary: Project memory: git-tracked working state, jev-mem decisions, and original evidence
+Project-URL: Repository, https://github.com/illescasDaniel/agemem
+Project-URL: Documentation, https://github.com/illescasDaniel/agemem/blob/main/docs/INSTALLATION.md
+Project-URL: Issues, https://github.com/illescasDaniel/agemem/issues
+Author-email: Daniel Illescas Romero <illescas.daniel@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY.md
+License-File: agemem/LICENSE.raw-rag
+License-File: agemem/notes/LICENSE.jevmem
+Requires-Python: <3.15,>=3.12
+Requires-Dist: fastembed<1,>=0.8.1
+Requires-Dist: mcp<3,>=2
+Requires-Dist: numpy<3,>=2.4
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: tomlkit<1,>=0.13
+Requires-Dist: typesafe-sdk<1,>=0.7.2
+Provides-Extra: compatibility
+Requires-Dist: jevmem==0.4.0; extra == 'compatibility'
+Provides-Extra: raw
+Requires-Dist: tiktoken<1,>=0.8; extra == 'raw'
+Description-Content-Type: text/markdown
+
+# agemem
+
+[![PyPI](https://img.shields.io/pypi/v/agemem?logo=pypi&label=PyPI)](https://pypi.org/project/agemem/)
+
+Experimental coding-project memory: a readable Markdown memory bank, screened SQLite notes, and cited original evidence. Jev is the default decision model. GPU-only QSIV, local ollaya `jevk5:4b`, and a QSIV → Jev confidence cascade are optional.
+
+The answering agent receives current context, selected durable notes and source excerpts. Decision models screen, classify and select memories; your coding agent writes the final answer. No automatic conversation capture or automatic bank rewriting is installed.
+
+![Agemem architecture](https://raw.githubusercontent.com/illescasDaniel/agemem/main/docs/diagrams/architecture.svg)
+
+## Install and use
+
+Requires Git and [uv](https://docs.astral.sh/uv/). From your project directory:
+
+```bash
+uvx --python 3.12 agemem@0.1.0 project init
+```
+
+Or paste this prompt into your coding agent:
+
+> Integrate Agemem 0.1.0 into this project using the linked installation and
+> agent-integration guides. Inspect the environment and existing setup first.
+> Ask which clients to configure (Claude Code only, or also Cursor/Codex if
+> detected), whether to use hosted Jev, local GPU QSIV, or the experimental
+> QSIV → Jev cascade, and any installation constraints. Recommend considering
+> the cascade if I have a compatible NVIDIA GPU. Explain QSIV's hardware and
+> download requirements and that cascade fallback uses hosted Jev. Have me supply
+> a Jev key privately through configuration or the environment, never in chat.
+> Run `uvx --python 3.12 agemem@0.1.0 project init --model <jev|qsiv> --mcp <selected clients> --no-input`
+> with the agreed choices; `claude` means Claude Code. For cascade, initialize
+> with QSIV and then configure the cascade as described in the local backends
+> guide; it is not a `--model` option. Preserve existing settings
+> and guidance, resolve conflicts with me, and add the suggested memory workflow
+> to the appropriate agent instructions. Agree on validation, run provider
+> diagnostics and an MCP handshake/tool-list/recall smoke test, and ask before
+> tests that incur hosted API charges. Report what passed, any skipped checks,
+> and required client restart or approval steps.
+
+Setup connects Codex, Cursor or Claude Code and configures hosted Jev or local
+GPU QSIV. Restart your client and enable the server.
+
+If you have a compatible NVIDIA GPU, consider the experimental [confidence
+cascade](https://github.com/illescasDaniel/agemem/blob/main/docs/LOCAL_BACKENDS.md#confidence-cascade):
+QSIV handles decisions locally and sends low-confidence decisions to hosted Jev.
+It requires both QSIV setup and a Jev key; fallback can incur API charges. The
+default cutoff is not a guarantee of correctness, and cascade may be slower.
+
+### Give your agent memory instructions
+
+Add the [suggested memory workflow](https://github.com/illescasDaniel/agemem/blob/main/docs/AGENT_INTEGRATION.md)
+to your project’s agent instructions (for example, `AGENTS.md` for Codex or
+`CLAUDE.md` for Claude Code). This tells the agent when to recall, verify,
+capture and maintain memory; installation does not edit these files.
+
+[Claude/Codex lifecycle hooks](https://github.com/illescasDaniel/agemem/blob/main/docs/HOOKS.md)
+load local context automatically and are installed by default for those clients.
+Use `--no-hooks` to skip installation. Hooks complement
+the instructions: they supply context, while the instructions guide how the
+agent uses and updates memory.
+See the [installation guide](https://github.com/illescasDaniel/agemem/blob/main/docs/INSTALLATION.md) for details. For development, [install from source](https://github.com/illescasDaniel/agemem/blob/main/docs/INSTALLATION.md#development-installation).
+
+## How it works
+
+The default is local BM25 + dense retrieval, combined with bank context and screened notes. An optional retrieval backend adapts RAW-RAG’s token chunking and dense/reranking pipeline. The default incorporates original evidence without depending on RAW-RAG's entire pipeline. [RAW-RAG setup](https://github.com/illescasDaniel/agemem/blob/main/docs/RAW_RAG.md) includes a validated offline MCP path with local embedding/reranking models and no paid retrieval API.
+
+Project config and bank files are readable; SQLite notes, source snapshots and vectors live under ignored `.agemem/local/`. Notes are project- and branch-scoped, unless explicitly shared. Source excerpts include provenance; obsolete snapshots require `--history`. Recall always searches raw sources, even when the note-only sufficiency check succeeds. Its context budget uses regex units, not an exact model tokenizer count.
+
+![Recall combines working context, durable notes and original evidence](https://raw.githubusercontent.com/illescasDaniel/agemem/main/docs/diagrams/recall.svg)
+
+Indexing applies file selection, size and secret filters. Filters are best-effort: inspect material before calling hosted decisions. Retrieved text is untrusted data. Hosted Jev can receive selected memory/source context during screening and recall; indexing itself makes no hosted calls.
+
+The MCP is the intended product interface; the note engine now incorporates selected MIT-licensed jev-mem code without requiring its package. See [implementation boundaries and release direction](https://github.com/illescasDaniel/agemem/blob/main/docs/ARCHITECTURE.md),
+[configuration](https://github.com/illescasDaniel/agemem/blob/main/docs/CONFIGURATION.md), [local backends](https://github.com/illescasDaniel/agemem/blob/main/docs/LOCAL_BACKENDS.md),
+and the [editable PlantUML diagrams](https://github.com/illescasDaniel/agemem/blob/main/docs/diagrams/README.md).
+
+## Evaluation
+
+On 50 author-labeled synthetic typed decisions: Jev 49/50, QSIV 42/50, cascade 49/50. At a fixed 0.90 native confidence cutoff the cascade kept 16 locally and sent 34 to Jev. This is an exploratory decision test, not proof of improved coding-task outcomes. The cascade is slower in this run and remains experimental.
+
+A controlled coding-memory selection evaluation uses the fixtures in `evaluation/`. The ten final fixtures scored Jev 9/10, QSIV 7/10 and cascade 10/10; QSIV accepted 5/6 unsupported proposed memories. These author-created fixtures do not establish end-to-end coding improvement. See [standalone QSIV setup](https://github.com/illescasDaniel/agemem/blob/main/docs/QSIV_INSTALLATION.md).
+
+Runtime utilities live in `agemem/evidence.py`. The historical comparison harness has been removed; current evaluation fixtures remain available. Reports and findings are local maintainer artifacts.
+
+See the [release checklist](https://github.com/illescasDaniel/agemem/blob/main/docs/RELEASE_0.1.0.md) and [CI/publishing guide](https://github.com/illescasDaniel/agemem/blob/main/docs/PUBLISHING.md).
+
+## Attribution
+
+Agemem combines selected work from these projects and providers:
+
+- [jev-mem](https://github.com/illescasDaniel/jev-mem): adapted MIT-licensed SQLite notes, screening, retrieval and maintenance code; [full notice](https://github.com/illescasDaniel/agemem/blob/main/agemem/notes/LICENSE.jevmem).
+- [RAW-RAG](https://github.com/Litmeb/RAW-RAG): adapted MIT-licensed token-window and dense/reranking retrieval; [full notice](https://github.com/illescasDaniel/agemem/blob/main/agemem/LICENSE.raw-rag) and [adaptation details](https://github.com/illescasDaniel/agemem/blob/main/agemem/RAW_RAG_ATTRIBUTION.md).
+- [QSIV](https://huggingface.co/djinn-san/QSIV): optional local decision model and runtime, downloaded separately under Apache-2.0 with its original LICENSE and NOTICE.
+- [Jev / TypeSafe AI](https://typesafe.ai): default hosted decision provider through its separately installed [Python SDK](https://github.com/typesafe-ai/typesafe-sdk-python); Jev weights and service implementation are not bundled.
+
+See [third-party attribution](https://github.com/illescasDaniel/agemem/blob/main/THIRD_PARTY.md) for versions, source hashes, license boundaries and additional credits.
+
+## Checks
+
+```bash
+.venv/bin/python -m unittest discover -s tests_live -q
+```

agemem-0.1.0/README.md

@@ -0,0 +1,101 @@
+# agemem
+
+[![PyPI](https://img.shields.io/pypi/v/agemem?logo=pypi&label=PyPI)](https://pypi.org/project/agemem/)
+
+Experimental coding-project memory: a readable Markdown memory bank, screened SQLite notes, and cited original evidence. Jev is the default decision model. GPU-only QSIV, local ollaya `jevk5:4b`, and a QSIV → Jev confidence cascade are optional.
+
+The answering agent receives current context, selected durable notes and source excerpts. Decision models screen, classify and select memories; your coding agent writes the final answer. No automatic conversation capture or automatic bank rewriting is installed.
+
+![Agemem architecture](https://raw.githubusercontent.com/illescasDaniel/agemem/main/docs/diagrams/architecture.svg)
+
+## Install and use
+
+Requires Git and [uv](https://docs.astral.sh/uv/). From your project directory:
+
+```bash
+uvx --python 3.12 agemem@0.1.0 project init
+```
+
+Or paste this prompt into your coding agent:
+
+> Integrate Agemem 0.1.0 into this project using the linked installation and
+> agent-integration guides. Inspect the environment and existing setup first.
+> Ask which clients to configure (Claude Code only, or also Cursor/Codex if
+> detected), whether to use hosted Jev, local GPU QSIV, or the experimental
+> QSIV → Jev cascade, and any installation constraints. Recommend considering
+> the cascade if I have a compatible NVIDIA GPU. Explain QSIV's hardware and
+> download requirements and that cascade fallback uses hosted Jev. Have me supply
+> a Jev key privately through configuration or the environment, never in chat.
+> Run `uvx --python 3.12 agemem@0.1.0 project init --model <jev|qsiv> --mcp <selected clients> --no-input`
+> with the agreed choices; `claude` means Claude Code. For cascade, initialize
+> with QSIV and then configure the cascade as described in the local backends
+> guide; it is not a `--model` option. Preserve existing settings
+> and guidance, resolve conflicts with me, and add the suggested memory workflow
+> to the appropriate agent instructions. Agree on validation, run provider
+> diagnostics and an MCP handshake/tool-list/recall smoke test, and ask before
+> tests that incur hosted API charges. Report what passed, any skipped checks,
+> and required client restart or approval steps.
+
+Setup connects Codex, Cursor or Claude Code and configures hosted Jev or local
+GPU QSIV. Restart your client and enable the server.
+
+If you have a compatible NVIDIA GPU, consider the experimental [confidence
+cascade](https://github.com/illescasDaniel/agemem/blob/main/docs/LOCAL_BACKENDS.md#confidence-cascade):
+QSIV handles decisions locally and sends low-confidence decisions to hosted Jev.
+It requires both QSIV setup and a Jev key; fallback can incur API charges. The
+default cutoff is not a guarantee of correctness, and cascade may be slower.
+
+### Give your agent memory instructions
+
+Add the [suggested memory workflow](https://github.com/illescasDaniel/agemem/blob/main/docs/AGENT_INTEGRATION.md)
+to your project’s agent instructions (for example, `AGENTS.md` for Codex or
+`CLAUDE.md` for Claude Code). This tells the agent when to recall, verify,
+capture and maintain memory; installation does not edit these files.
+
+[Claude/Codex lifecycle hooks](https://github.com/illescasDaniel/agemem/blob/main/docs/HOOKS.md)
+load local context automatically and are installed by default for those clients.
+Use `--no-hooks` to skip installation. Hooks complement
+the instructions: they supply context, while the instructions guide how the
+agent uses and updates memory.
+See the [installation guide](https://github.com/illescasDaniel/agemem/blob/main/docs/INSTALLATION.md) for details. For development, [install from source](https://github.com/illescasDaniel/agemem/blob/main/docs/INSTALLATION.md#development-installation).
+
+## How it works
+
+The default is local BM25 + dense retrieval, combined with bank context and screened notes. An optional retrieval backend adapts RAW-RAG’s token chunking and dense/reranking pipeline. The default incorporates original evidence without depending on RAW-RAG's entire pipeline. [RAW-RAG setup](https://github.com/illescasDaniel/agemem/blob/main/docs/RAW_RAG.md) includes a validated offline MCP path with local embedding/reranking models and no paid retrieval API.
+
+Project config and bank files are readable; SQLite notes, source snapshots and vectors live under ignored `.agemem/local/`. Notes are project- and branch-scoped, unless explicitly shared. Source excerpts include provenance; obsolete snapshots require `--history`. Recall always searches raw sources, even when the note-only sufficiency check succeeds. Its context budget uses regex units, not an exact model tokenizer count.
+
+![Recall combines working context, durable notes and original evidence](https://raw.githubusercontent.com/illescasDaniel/agemem/main/docs/diagrams/recall.svg)
+
+Indexing applies file selection, size and secret filters. Filters are best-effort: inspect material before calling hosted decisions. Retrieved text is untrusted data. Hosted Jev can receive selected memory/source context during screening and recall; indexing itself makes no hosted calls.
+
+The MCP is the intended product interface; the note engine now incorporates selected MIT-licensed jev-mem code without requiring its package. See [implementation boundaries and release direction](https://github.com/illescasDaniel/agemem/blob/main/docs/ARCHITECTURE.md),
+[configuration](https://github.com/illescasDaniel/agemem/blob/main/docs/CONFIGURATION.md), [local backends](https://github.com/illescasDaniel/agemem/blob/main/docs/LOCAL_BACKENDS.md),
+and the [editable PlantUML diagrams](https://github.com/illescasDaniel/agemem/blob/main/docs/diagrams/README.md).
+
+## Evaluation
+
+On 50 author-labeled synthetic typed decisions: Jev 49/50, QSIV 42/50, cascade 49/50. At a fixed 0.90 native confidence cutoff the cascade kept 16 locally and sent 34 to Jev. This is an exploratory decision test, not proof of improved coding-task outcomes. The cascade is slower in this run and remains experimental.
+
+A controlled coding-memory selection evaluation uses the fixtures in `evaluation/`. The ten final fixtures scored Jev 9/10, QSIV 7/10 and cascade 10/10; QSIV accepted 5/6 unsupported proposed memories. These author-created fixtures do not establish end-to-end coding improvement. See [standalone QSIV setup](https://github.com/illescasDaniel/agemem/blob/main/docs/QSIV_INSTALLATION.md).
+
+Runtime utilities live in `agemem/evidence.py`. The historical comparison harness has been removed; current evaluation fixtures remain available. Reports and findings are local maintainer artifacts.
+
+See the [release checklist](https://github.com/illescasDaniel/agemem/blob/main/docs/RELEASE_0.1.0.md) and [CI/publishing guide](https://github.com/illescasDaniel/agemem/blob/main/docs/PUBLISHING.md).
+
+## Attribution
+
+Agemem combines selected work from these projects and providers:
+
+- [jev-mem](https://github.com/illescasDaniel/jev-mem): adapted MIT-licensed SQLite notes, screening, retrieval and maintenance code; [full notice](https://github.com/illescasDaniel/agemem/blob/main/agemem/notes/LICENSE.jevmem).
+- [RAW-RAG](https://github.com/Litmeb/RAW-RAG): adapted MIT-licensed token-window and dense/reranking retrieval; [full notice](https://github.com/illescasDaniel/agemem/blob/main/agemem/LICENSE.raw-rag) and [adaptation details](https://github.com/illescasDaniel/agemem/blob/main/agemem/RAW_RAG_ATTRIBUTION.md).
+- [QSIV](https://huggingface.co/djinn-san/QSIV): optional local decision model and runtime, downloaded separately under Apache-2.0 with its original LICENSE and NOTICE.
+- [Jev / TypeSafe AI](https://typesafe.ai): default hosted decision provider through its separately installed [Python SDK](https://github.com/typesafe-ai/typesafe-sdk-python); Jev weights and service implementation are not bundled.
+
+See [third-party attribution](https://github.com/illescasDaniel/agemem/blob/main/THIRD_PARTY.md) for versions, source hashes, license boundaries and additional credits.
+
+## Checks
+
+```bash
+.venv/bin/python -m unittest discover -s tests_live -q
+```

agemem-0.1.0/THIRD_PARTY.md

@@ -0,0 +1,70 @@
+# Attribution and third-party material
+
+Agemem builds on the following projects and services. Source-code licenses,
+model licenses and hosted-service terms apply separately.
+
+## jev-mem
+
+Selected code in `agemem/notes/` is adapted from
+[jev-mem](https://github.com/illescasDaniel/jev-mem) 0.4.0, copyright 2026
+Daniel Illescas Romero, under the MIT License. The complete copyright and
+permission notice is bundled in [LICENSE.jevmem](agemem/notes/LICENSE.jevmem).
+[UPSTREAM.json](agemem/notes/UPSTREAM.json) records original file hashes and
+adaptations.
+
+The SQLite store, policy prompts, screening, retrieval, consolidation and
+matrix index are retained. The upstream hosted client, global settings, hooks
+and remote index backends are excluded. Agemem's live MCP uses this internal
+adaptation; the external jev-mem package is optional for database compatibility tests only.
+
+## RAW-RAG
+
+[RAW-RAG](https://github.com/Litmeb/RAW-RAG), copyright 2026 RAW-RAG
+contributors, supplies the overlapping token-window and dense candidate /
+reranking pipeline adapted in [agemem/raw_rag.py](agemem/raw_rag.py). The full
+MIT notice is bundled in [LICENSE.raw-rag](agemem/LICENSE.raw-rag).
+[RAW_RAG_ATTRIBUTION.md](agemem/RAW_RAG_ATTRIBUTION.md) records the pinned
+revision `95639191e9547219b426710e50fe1a36235e26fc`, reference-file hash and
+changes.
+
+The live implementation uses local BGE embeddings and MiniLM reranking, with
+Agemem's source provenance and scope filtering. It omits upstream answer
+generation and remote model clients. This is an adaptation, not a reproduction
+of RAW-RAG's full method or published results. It does not require a RAW-RAG
+checkout.
+
+## QSIV
+
+[QSIV](https://huggingface.co/djinn-san/QSIV), copyright 2026 the QSIV authors,
+is an optional local decision runtime and model. Setup fetches revision
+`f1ee842daf758c0ab535cf7d281c85439d6e4b25`; the full runtime and its weights are not bundled in the Agemem package. The downloaded model directory
+retains its complete Apache-2.0
+[LICENSE](https://huggingface.co/djinn-san/QSIV/blob/f1ee842daf758c0ab535cf7d281c85439d6e4b25/LICENSE)
+and [NOTICE](https://huggingface.co/djinn-san/QSIV/blob/f1ee842daf758c0ab535cf7d281c85439d6e4b25/NOTICE).
+
+QSIV's NOTICE credits the Qwen team / Alibaba Cloud for Qwen3.5-0.8B-Base and
+its tokenizer, as well as the Gated DeltaNet and flash-linear-attention work.
+Those notices and dependency licenses remain applicable. Our installer changes
+only the downloaded runtime's NumPy dependency pin to match the tested
+environment; it does not change QSIV inference code or weights.
+
+## Jev and TypeSafe AI
+
+[Jev / TypeSafe AI](https://typesafe.ai) provides the default hosted decision
+service, accessed through the
+[TypeSafe Python SDK](https://github.com/typesafe-ai/typesafe-sdk-python).
+Agemem includes its own provider adapter and depends on the SDK as a separately
+installed package, which retains its own MIT license. It does not copy or
+redistribute Jev model weights or the hosted service's implementation.
+Hosted API terms and metering apply when that provider is explicitly used;
+no credentials are included in this repository.
+
+## Other material
+
+The [memory-bank](https://github.com/illescasDaniel/memory-bank) project is a
+design reference; this workspace does not install a copy of its skill.
+
+
+Embedding and reranking weights download separately through FastEmbed and
+retain their respective model licenses. Other installed dependencies retain
+their own licenses; the notices above do not relicense those dependencies.

agemem-0.1.0/agemem/LICENSE.raw-rag

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

agemem-0.1.0/agemem/RAW_RAG_ATTRIBUTION.md

@@ -0,0 +1,22 @@
+# RAW-RAG attribution
+
+`raw_rag.py` adapts the overlapping token-window algorithm and dense candidate /
+reranking pipeline from RAW-RAG, MIT License, copyright 2026 RAW-RAG contributors.
+Full upstream license: `LICENSE.raw-rag`, included in this package.
+
+Upstream: https://github.com/Litmeb/RAW-RAG
+Revision: `95639191e9547219b426710e50fe1a36235e26fc`
+Reference: `methods/EverCore/evaluation/src/adapters/rag_adapter.py`
+Reference file SHA256: `997c35db93feea77eed897b3d5640bd9cd6f114da40bff5128efae65a6466637`
+
+This is a deliberate adaptation, not an upstream reproduction. Source records
+are chunked separately (256 cl100k tokens, overlap32), with exact source IDs.
+The original conversation headers, cross-turn windows, temporal filters,
+remote embedding/reranking/answer clients, incremental conversation ingestion,
+dynamic selection and optional PostgreSQL support are omitted. Agemem filters
+project, branch and current snapshot visibility before calling this adapter.
+BGE/MiniLM run locally; dense cosine top128 feeds rerank top15, followed by
+Agemem's context budget. Model licenses remain separate from source licensing.
+
+The live service uses only this adapted implementation; no upstream checkout or
+comparison harness is required.

agemem-0.1.0/agemem/__init__.py

@@ -0,0 +1,2 @@
+"""Live project memory composed from a memory bank, jev-mem and source retrieval."""
+__version__ = "0.1.0"

agemem-0.1.0/agemem/cli.py

@@ -0,0 +1,129 @@
+"""User-facing project setup and live memory commands."""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .engine import Engine
+from .project import initialize
+from .config import initialize_user_config, doctor, provider_options
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd(), help="Project checkout to use")
+    parser.add_argument("--offline", action="store_true", help="Never use hosted decisions or download embedding weights")
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("project", help="Set up a project and its MCP connection")
+    project_init = p.add_subparsers(dest="project_command", required=True).add_parser("init", help="Ensure user config, project files, index and MCP registration")
+    clients = project_init.add_mutually_exclusive_group()
+    clients.add_argument("--client", choices=["codex", "cursor", "claude-code"], help="Register one client")
+    clients.add_argument("--mcp", nargs="+", choices=["codex", "cursor", "claude", "claude-code"], help="Register selected clients; claude means Claude Code")
+    project_init.add_argument("--model", choices=["jev", "qsiv"], help="Select the decision provider without prompting")
+    hook_options = project_init.add_mutually_exclusive_group()
+    hook_options.add_argument("--no-hooks", dest="hooks", action="store_false", help="Do not install lifecycle hooks")
+    hook_options.add_argument("--hooks", dest="hooks", action="store_true", help=argparse.SUPPRESS)
+    project_init.set_defaults(hooks=True)
+    project_init.add_argument("--executable", type=Path, help="Use an installed agemem executable instead of uvx (source testing)")
+    project_init.add_argument("--no-input", action="store_true", help="Never prompt; fail when required setup choices are missing")
+    project_init.add_argument("--retrieval", choices=["hybrid", "bm25", "raw-rag"], default="hybrid")
+    project_init.add_argument("--embedder", default="BAAI/bge-small-en-v1.5")
+    p = sub.add_parser("config", help="Manage user configuration")
+    p.add_subparsers(dest="config_command", required=True).add_parser("init", help="Create a private YAML template without overwriting existing settings")
+    p = sub.add_parser("provider", help="Set up optional local providers")
+    provider_sub = p.add_subparsers(dest="provider_command", required=True)
+    setup = provider_sub.add_parser("setup", help="Explicitly download models and install an isolated runtime")
+    setup.add_argument("provider_name", choices=["qsiv"])
+    setup.add_argument("--model-directory", type=Path)
+    setup.add_argument("--runtime-directory", type=Path)
+    setup.add_argument("--dry-run", action="store_true", help="Show actions without downloads or filesystem changes")
+    sub.add_parser("doctor", help="Check provider setup without inference or API calls")
+    p = sub.add_parser("init", help="Create missing bank/config files; preserve existing memory")
+    p.add_argument("--retrieval", choices=["hybrid", "bm25", "raw-rag"], default="hybrid")
+    p.add_argument("--embedder", default="BAAI/bge-small-en-v1.5")
+    sub.add_parser("index", help="Snapshot selected tracked project files; no hosted calls")
+    p = sub.add_parser("capture", help="Archive original text as untrusted source evidence")
+    p.add_argument("text")
+    p.add_argument("--label", default="event")
+    p.add_argument("--shared", action="store_true")
+    p = sub.add_parser("remember", help="Write a durable note through jev-mem's actual screens")
+    p.add_argument("text")
+    p.add_argument("--source-id")
+    p.add_argument("--shared", action="store_true")
+    p = sub.add_parser("recall", help="Read current bank, recall notes, and retrieve source evidence live")
+    p.add_argument("query")
+    p.add_argument("--budget", type=int)
+    p.add_argument("--history", action="store_true", help="Also search older file snapshots on this branch")
+    sub.add_parser("maintain", help="Screen pending notes and run jev-mem consolidation")
+    sub.add_parser("mcp", help="Run the project's MCP server over stdio")
+    p = sub.add_parser("mcp-install", help="Register this project with a coding client")
+    p.add_argument("--client", choices=["codex", "cursor", "claude-code"], help="Prompt when omitted")
+    p.add_argument("--dry-run", action="store_true", help="Preview registration without changing client configuration")
+    p.add_argument("--executable", type=Path, help="Use an installed agemem executable instead of uvx")
+    p = sub.add_parser("hooks-install", help="Install optional read-only lifecycle hooks")
+    p.add_argument("--client", nargs="+", choices=["codex", "claude", "claude-code"], required=True)
+    p.add_argument("--executable", type=Path)
+    p.add_argument("--dry-run", action="store_true")
+    p = sub.add_parser("hook", help="Handle client lifecycle JSON on stdin; local read-only context")
+    p.add_argument("event", choices=["session-start", "user-prompt"])
+    args = parser.parse_args()
+    try:
+        if args.command == "project":
+            from .setup import initialize_project
+            result = initialize_project(args.project, args.client, args.retrieval, args.embedder, args.offline, model=args.model, clients=args.mcp, no_input=args.no_input, hooks=args.hooks, executable=args.executable)
+        elif args.command == "config":
+            result = initialize_user_config()
+        elif args.command == "mcp-install":
+            from .mcp_install import install
+            result = install(args.project, args.client, args.dry_run, args.offline, args.executable)
+        elif args.command == "hooks-install":
+            from .hooks import install
+            result = install(args.project, args.client, args.executable, args.dry_run)
+        elif args.command == "hook":
+            from .hooks import run
+            run(args.project, args.event)
+            return
+        elif args.command == "provider":
+            from .providers import setup_qsiv
+            options = provider_options({})
+            if options["qsiv_runtime"] != "fp8":
+                raise ValueError("Automatic QSIV setup currently supports runtime fp8 only")
+            runtime_python = options.get("qsiv_python")
+            runtime_directory = args.runtime_directory or (Path(runtime_python).parent.parent if runtime_python else None)
+            result = setup_qsiv(directory=args.model_directory or options.get("qsiv_directory"),
+                                runtime_directory=runtime_directory, dry_run=args.dry_run)
+        elif args.command == "doctor":
+            result = doctor(args.project)
+        elif args.command == "init":
+            result = initialize(args.project, args.retrieval, args.embedder)
+        elif args.command == "mcp":
+            from .mcp import serve
+            serve(args.project, args.offline)
+            return
+        else:
+            engine = Engine(args.project, args.offline)
+            try:
+                if args.command == "index":
+                    result = engine.index()
+                elif args.command == "capture":
+                    result = engine.capture(args.text, args.label, args.shared)
+                elif args.command == "remember":
+                    result = engine.remember(args.text, args.source_id, args.shared)
+                elif args.command == "recall":
+                    result = engine.recall(args.query, args.budget, args.history)
+                else:
+                    result = engine.maintain()
+            finally:
+                engine.close()
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        if args.command == "doctor" and not result["ok"]:
+            raise SystemExit(1)
+    except Exception as exc:
+        # Do not echo SDK exception bodies, key-bearing URLs or supplied source text.
+        message = str(exc) if isinstance(exc, ValueError) else "See installation/runtime diagnostics; provider details omitted"
+        print(json.dumps({"error": type(exc).__name__, "message": message}), file=sys.stderr)
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    main()