KHMS memory boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

KHMS is in scope as a file-based long-term memory system serving LLM agents, not as the enclosing agent runtime. Its intended use is to retain evidence-linked knowledge across sessions and bring relevant retained knowledge back into an agent's context. The target is the whole shipped KHMS system: operational instructions, model-stage prompts, shell drivers, Python helpers, Claude Code hook integration, maintenance tools and evaluators. The separately deployed agent CLI supplies model execution; that does not make the shipped drivers external to KHMS. SRC-1: README.md, AGENTS.md, claude-code/README.md, tools/nightly_distill.sh, tools/permark.py.

The source declares the memory and admission design:

Around that storage layer sits the part that makes it work in practice — hook-driven recall that pushes relevant cards into the session before the agent asks for them, and a propose → review → approve pipeline in which background jobs may only propose and nothing enters the knowledge directory unreviewed. --- README.md

This is a whole-system boundary rather than a retrieval-library boundary. Initial tracing covers the paths that produce journal and generated MARK records, prepare model inputs, retain proposals and checkpoints, admit reviewed cards, regenerate views, later retrieve cards, and propose or apply maintenance. It includes the prescribed human/agent actions as doctrine, without treating their performance as observed operation:

• Capture and proposal: journal MARK instructions in AGENTS.md; transcript/git generation and durable generated records in tools/nightly_distill.sh; the generator prompt in tools/prompts/nightly-generate.md; queue evaluation through tools/permark.py and tools/prompts/nightly-marks.md. The driver calls the evaluator and commits its post-checked output into carry batches; the current route is not inferred solely from the older sweep/consolidate description in the specification. SRC-1: those paths, including tools/nightly_distill.sh's generator commit and MARK-stage call sites.
• Admission and persistence: tools/approve_inbox.py maps temporary IDs to allocated IDs, writes card files, records review completion, updates relations and invokes tools/build_views.py; the latter validates cards and generates views and MEMORY.md. Review authorization is an operational requirement, not evidence that every invocation has received human approval. SRC-1: tools/approve_inbox.py, tools/build_views.py, AGENTS.md.
• Later consumption: the shipped tools/recall.sh enters tools/khms_recall_hybrid.py; the hook loads retained cards through the search layer, runs selection, saves session state and emits context. claude-code/settings.hooks.json supplies the actual example event wiring. spec/bootstrap-digest.md and AGENTS.md prescribe loading the generated index and explicit recall. SRC-1: those paths and tools/khms_hook.py.
• Maintenance and distribution: include nightly retry/carry and ledger machinery, weekly synthesis and its prompts, triage and reviewed application, daily validity proposals, archive/erratum tooling, version-history access and read-only export. Representative initial inspection covers tools/nightly_distill.sh, tools/weekly_synthesis.sh, tools/prompts/weekly-synthesis.md, tools/khms_triage.py, tools/apply_triage.py, tools/khms_validity_daily.sh, tools/khms_archive.py, tools/khms_versions.py and tools/khms_export.sh. The remaining helpers at this same pin remain included evidence for subsequent tracing, not excluded responsibilities.
• Evaluation: include synthetic tests, the production-path retrieval evaluator, injection-use measurement guidance and historical triage experiment tooling. These are evaluation designs and attributed reports, not test results observed in this run. SRC-1: tests/test_night_pipeline.py, tests/test_onboarding.py, tools/eval/run_eval.py, docs/measuring-injection.md, tools/khms_experiments/README.md.

The model dependence is visible in the evaluator's shipped command construction, rather than inferred from its name:

def claude_cmd(agent, model, rules, effort=None): return [agent, "-p", "--model", model, "--output-format", "json", "--tools", "", "--system-prompt", rules, "--setting-sources", "", "--strict-mcp-config", "--no-session-persistence", "--effort", effort or EFFORT]

--- tools/permark.py

The return path into model context is explicit:

def emit(event, text): print(json.dumps({"hookSpecificOutput": {"hookEventName": event, "additionalContext": text}})) --- tools/khms_hook.py

Tracked-tree coverage

Every top-level tracked file or directory is classified below. “Included” denotes functional and evidentiary scope, not a claim that every line has already been inspected. Material entry points and their consumers were initially traced above; individual helper internals not yet inspected remain available at the same registered commit.

External boundary and evidence limits

The frozen evidence is SRC-1 at full commit f739eb976dab199fd4cd64e352192cc0b112c047, with applicability cutoff 2026-11-08. The acquired checkout's HEAD matched that pin and its status was clean at initial inspection. Evidence is code-grounded: shipped source establishes inspectable control flow, while operational instructions establish intent. No target code, test, model call or example was executed.

External dependencies are the enclosing Claude Code/headless-agent runtime and its providers; Python/PyYAML and Linux shell utilities; the deployment scheduler and credentials; optional embedding libraries/model artifacts; and optional Nextcloud/DAV storage history. KHMS's shipped integration and client code remain included, but dependency implementation is outside SRC-1. This prevents conclusions about host scheduling guarantees, actual model behavior, embedding quality, or storage-service durability. SRC-1: claude-code/README.md, requirements.txt, tools/permark.py, tools/embed_server.py, tools/khms_versions.py.

The real memory base, private configuration and prompt extensions, deployment transcripts/logs, historical server versions and experiment answer caches were not acquired. These are unavailable evidence, not deliberately omitted shipped paths. Their absence prevents verifying reference-deployment performance numbers, successful recovery, actual review adherence, completeness of captured knowledge, and the usefulness of cards in later real decisions. docs/measuring-injection.md provides reported operation, not the underlying trace. The examples and fake-agent tests cannot fill that gap. External links in documentation are not additional registered sources and were not followed. SRC-1: docs/measuring-injection.md, examples/README.md, tests/test_night_pipeline.py, tools/khms_experiments/README.md.

Source register