# kioku-mesh - Doramagic AI Context Pack

> Purpose: pre-work context for the user's host AI. This pack does not prove that the project has been installed, run, or validated.

## Project

- canonical_name: `h-wata/kioku-mesh`
- capability: Shared memory for AI coding agents, across tools and machines. Local-first SQLite, optional Zenoh+RocksDB mesh, MCP-native.
- expected_user_outcome: Shared memory for AI coding agents, across tools and machines. Local-first SQLite, optional Zenoh+RocksDB mesh, MCP-native.

## Operating Boundaries

- Do not claim that the project has been installed, run, called through an API, or used on local files unless separate evidence proves it.
- Project facts must come from repo evidence, Claim Graph, or explicit source references.
- When a capability is not verified, mark it as unverified instead of completing it as fact.
- publish_status: `publishable`
- blocking_gaps: none

---

## Doramagic Context Augmentation

The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints.

## Human Manual Outline

Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph.

Host AI hard rules:
- Do not treat page titles, section order, summaries, or importance values as factual project evidence.
- When explaining the Human Manual outline, state that it is only a reading route or salience signal.
- Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph.

- **Project Overview & System Architecture**: importance `high`
  - source_paths: README.md, docs/Spec.md, src/mesh_mem/__init__.py, src/mesh_mem/__main__.py, src/mesh_mem/memory/backend.py
- **Observations, Storage & Local Index**: importance `high`
  - source_paths: src/mesh_mem/core/models.py, src/mesh_mem/memory/store.py, src/mesh_mem/memory/local_index.py, src/mesh_mem/memory/pending_queue.py, src/mesh_mem/memory/replication.py
- **Mesh Networking, Replication & Security**: importance `high`
  - source_paths: src/mesh_mem/core/transport.py, src/mesh_mem/core/tls.py, src/mesh_mem/core/keyspace.py, config/zenohd_home.json5, config/zenohd_office.json5
- **CLI, MCP Server & Messaging Layer**: importance `high`
  - source_paths: src/mesh_mem/__main__.py, src/mesh_mem/mcp_server.py, src/mesh_mem/mcp_install.py, src/mesh_mem/messaging/__init__.py, src/mesh_mem/messaging/keyspace.py

## Repo Inspection Evidence

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `a9327ee4673d4e6572f539e3764f42c17d6a804a`
- inspected_files: `README.md`, `pyproject.toml`, `docs/Spec.md`, `docs/adr/0001-zenoh-rocksdb-transport.md`, `docs/adr/0002-existence-based-tombstone.md`, `docs/adr/0003-python-side-filter-before-fts5.md`, `docs/adr/0004-identity-env-and-persistent-file.md`, `docs/adr/0005-gc-project-agnostic-scope.md`, `docs/adr/0006-hub-and-spoke-mesh-topology.md`, `docs/adr/0007-sqlite-local-index-sidecar.md`, `docs/adr/0008-gc-project-aware-and-o-n.md`, `docs/adr/0009-mcp-server-instructions-protocol.md`, `docs/adr/0010-zenoh-as-source-of-truth.md`, `docs/adr/0011-rebuild-shadow-delete-reconcile.md`, `docs/adr/0012-forward-compat-extras-side-channel.md`, `docs/adr/0013-drop-tier-1-from-public-architecture.md`, `docs/adr/0014-mtls-via-csr-private-ca.md`, `docs/adr/0015-cert-enrollment-copy-paste-default.md`, `docs/adr/0016-remove-localhost-init-mode.md`, `docs/adr/0017-dual-hub-spoke-topology.md`

Host AI hard rules:
- Without repo_clone_verified=true, do not claim that the source code has been read.
- Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts.
- Without quick_start_verified=true, do not claim that the Quick Start path has run successfully.

## Doramagic Pitfall Constraints

These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes.

### Constraint 1: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: mesh-mem v0.2.4
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: mesh-mem v0.2.4. Context: Observed when using python, windows
- Why it matters: Upgrade or migration may change expected behavior: mesh-mem v0.2.4
- Evidence: failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.2.4
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 2: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: mesh-mem v0.2.5
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: mesh-mem v0.2.5. Context: Observed when using python
- Why it matters: Upgrade or migration may change expected behavior: mesh-mem v0.2.5
- Evidence: failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.2.5
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 3: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: mesh-mem v0.3.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: mesh-mem v0.3.0. Context: Observed when using python, macos, linux
- Why it matters: Upgrade or migration may change expected behavior: mesh-mem v0.3.0
- Evidence: failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 4: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v0.3.1
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.3.1. Context: Observed when using python
- Why it matters: Upgrade or migration may change expected behavior: v0.3.1
- Evidence: failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.1
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 5: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v0.3.2
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.3.2. Context: Observed when using python
- Why it matters: Upgrade or migration may change expected behavior: v0.3.2
- Evidence: failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.2
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 6: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v0.3.3
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.3.3. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v0.3.3
- Evidence: failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.3.3
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 7: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: v0.4.0 — Mutual TLS for the mesh
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v0.4.0 — Mutual TLS for the mesh. Context: Observed when using python
- Why it matters: Upgrade or migration may change expected behavior: v0.4.0 — Mutual TLS for the mesh
- Evidence: failure_mode_cluster:github_release | https://github.com/h-wata/kioku-mesh/releases/tag/v0.4.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 8: Installation risk requires verification

- Trigger: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/h-wata/kioku-mesh/issues/167
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 9: Configuration risk requires verification

- Trigger: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/h-wata/kioku-mesh
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 10: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up)
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up). Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: design: hard authorization — mTLS cert subject ↔ Zenoh ACL for team/user scope (#185 follow-up)
- Evidence: failure_mode_cluster:github_issue | https://github.com/h-wata/kioku-mesh/issues/191
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.