# https://github.com/Richardyu114/Moryn Project Manual Generated at: 2026-07-03 23:41:49 UTC ## Table of Contents - [Overview & System Architecture](#page-1) - [Agent Integration & Command Surface](#page-2) - [Memory Lifecycle, Capture & Safety Model](#page-3) - [Dashboard, Sync & Operations](#page-4) ## Overview & System Architecture ### Related Pages Related topics: [Agent Integration & Command Surface](#page-2), [Memory Lifecycle, Capture & Safety Model](#page-3), [Dashboard, Sync & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/Richardyu114/Moryn/blob/main/README.md) - [docs/moryn-design.md](https://github.com/Richardyu114/Moryn/blob/main/docs/moryn-design.md) - [package.json](https://github.com/Richardyu114/Moryn/blob/main/package.json) - [src/core/types.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/types.ts) - [src/core/schema.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/schema.ts) - [src/core/engine.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/engine.ts) - [src/core/store.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/store.ts)
# Overview & System Architecture Moryn is a local-first memory, skill, and handoff layer for AI agents. It runs as a single Node.js CLI (`moryn`) installed globally via npm, and exposes an on-disk agent memory store that adjacent tools (including the bundled `moryn dashboard` and `moryn-agent-smoke` helpers) can read and write during an agent session. Source: [README.md:1-80]() ## Purpose & Scope The project targets a narrow but recurring problem in agent workflows: persistence of working memory, learned skills, and inter-session handoffs without depending on a remote service. Moryn treats the local filesystem as the source of truth and exposes a uniform abstraction over that storage so that agents authored in different environments share the same data layer. Source: [docs/moryn-design.md:1-60]() Scope boundaries for the current `0.1.x` line: - Single-machine, single-user operation. There is no cloud sync, multi-tenant model, or remote authn/authz layer in this release. Source: [docs/moryn-design.md:60-120]() - Public surface is a CLI plus a programmatic API consumed by agent runtimes. The npm package name is `@richardyu114/moryn` and the primary binary is `moryn`. Source: [package.json:1-40]() - Observability is supported locally via `moryn dashboard`, added in v0.1.1 so a developer can inspect a store during agent work without leaving the terminal. Source: [README.md:80-140]() ## Architectural Layers Moryn is structured as three concentric layers. Each layer has a single responsibility and a narrow contract with the layer below it. ```mermaid flowchart TB CLI["CLI Layer
moryn / moryn dashboard"] Engine["Engine Layer
src/core/engine.ts"] Store["Store Layer
src/core/store.ts"] Schema["Schema & Types
src/core/schema.ts, types.ts"] Disk[("Local
Filesystem")] CLI --> Engine Engine --> Schema Engine --> Store Store --> Disk Schema --> Engine ``` - CLI Layer. Entry points parse arguments, dispatch to the engine, and format output for humans (tables, JSON) or downstream tools. The two shipped executables — `moryn` and `moryn-agent-smoke` — share the same engine and store so that the smoke test exercises the real persistence path on a fresh install. Source: [package.json:20-60]() - Engine Layer. `src/core/engine.ts` coordinates read/write operations, applies schema validation, and enforces the invariants of the handoff protocol. Higher-level features (skill registration, memory recall, dashboard queries) compose primitives defined here. Source: [src/core/engine.ts:1-120]() - Store Layer. `src/core/store.ts` is the only module that performs filesystem I/O. Everything above it speaks in terms of typed records; everything below it is opaque bytes. This separation is what allows the dashboard and the smoke test to read the same data structure without coupling. Source: [src/core/store.ts:1-80]() ## Domain Model The shared vocabulary of Moryn lives in `src/core/types.ts` and is enforced by validators in `src/core/schema.ts`. Three record kinds dominate the model: - Memory entries — short, addressable notes an agent produces while working. - Skill entries — reusable procedures an agent has been promoted to use. - Handoff records — packaged state left for the next session or the next agent. Each kind has a stable identifier, a creation timestamp, and a payload that is validated against the corresponding schema before it reaches the store. Source: [src/core/types.ts:1-90]() The schema module produces a single typed error path on validation failure, which keeps the engine's error handling uniform across record kinds. Source: [src/core/schema.ts:1-70]() This shape — three record kinds, one schema per kind, one store path per kind — is deliberate. It is what lets the dashboard render heterogeneous records through a single read API. Source: [docs/moryn-design.md:120-180]() ## Storage & Local-First Design The store is the foundation of the local-first guarantee. All reads return immutable snapshots, all writes are sequenced through the engine, and writes are durable before the engine returns. Because the store is the only module with filesystem access, swapping the backing medium (for example, moving from a directory of JSON files to an embedded database) is a contained change. Source: [src/core/store.ts:80-160]() Two consequences follow: 1. Agents do not need a network round-trip to recall prior state, which makes Moryn usable in offline development environments and CI runners. Source: [README.md:40-100]() 2. The `moryn dashboard` command introduced in v0.1.1 can open the same store concurrently with a running agent and surface what the agent sees, which closes the loop between "what the agent stored" and "what a human can verify." Source: [README.md:100-160]() ## Component Responsibilities at a Glance | Module | Primary Responsibility | Notable Contract | | --- | --- | --- | | `src/core/types.ts` | Defines record shapes and IDs | Pure types, no I/O | | `src/core/schema.ts` | Validates payloads per kind | Throws a single typed validation error | | `src/core/engine.ts` | Orchestrates read/write flows | Never touches the filesystem directly | | `src/core/store.ts` | Persists and retrieves records | Only module with filesystem access | | `src/cli/*` (via `package.json` binaries) | User-facing commands | Delegates all logic to the engine | Source: [package.json:20-60](), [src/core/engine.ts:1-120](), [src/core/store.ts:1-80]() ## Operating Constraints The `0.1.x` line is an MVP. The release notes describe the package as a "local-first memory, skill, and handoff layer" and identify v0.1.1 as a patch that "keeps the public package on the 0.1.x line and adds a local observability dashboard." Source: [README.md:1-60]() Concretely, that means the architecture is optimized for a single developer iterating locally; concurrency semantics are intentionally simple, and the public schema may evolve before the `0.2.x` cutoff. Source: [docs/moryn-design.md:180-240]() Developers extending Moryn should add behavior at the engine boundary rather than reaching past it: new record kinds require a type, a schema, a store method, and an engine entry point, in that order. Source: [docs/moryn-design.md:240-300]() --- ## Agent Integration & Command Surface ### Related Pages Related topics: [Overview & System Architecture](#page-1), [Memory Lifecycle, Capture & Safety Model](#page-3)
Related Source Files The following source files were used to generate this page: - [src/cli.ts](https://github.com/Richardyu114/Moryn/blob/main/src/cli.ts) - [src/mcp/server.ts](https://github.com/Richardyu114/Moryn/blob/main/src/mcp/server.ts) - [src/core/host-adapter-registry.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/host-adapter-registry.ts) - [src/core/host-adapters.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/host-adapters.ts) - [src/core/agent-lifecycle.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-lifecycle.ts) - [src/core/agent-identity.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/agent-identity.ts)
# Agent Integration & Command Surface The **Agent Integration & Command Surface** is the outward-facing layer of Moryn through which developers, AI agents, and external runtimes reach the local-first memory, skill, and handoff store. It is intentionally split into three coordinated entry points — a CLI executable, a Model Context Protocol (MCP) server, and a pluggable host-adapter registry — so that the same underlying core APIs can be driven from a terminal, from a coding assistant, or from a third-party agent platform without divergent behavior. Source: [src/cli.ts:1-60]() The v0.1 release shipped the `moryn` CLI as the primary executable and `moryn-agent-smoke` as a post-install lifecycle probe, while v0.1.1 added `moryn dashboard` for inspecting store state during an agent session. Together these form the human- and automation-facing boundary documented in this page. Source: [README release notes v0.1 / v0.1.1]() ## CLI Executable and Subcommands The `moryn` binary is the most direct command surface. Installed globally via `npm install -g @richardyu114/moryn`, it parses arguments in `src/cli.ts`, routes subcommands to the appropriate core module, and writes structured output to stdout or to a local store path. Subcommands cover memory read/write, skill recall, handoff publishing, agent registration, and the v0.1.1 dashboard view. Source: [src/cli.ts:60-220]() The companion `moryn-agent-smoke` executable is wired into the package's post-install lifecycle. It performs a minimal end-to-end check — identity creation, a memory append/read cycle, and a handoff — so that integrators receive immediate feedback if the local environment cannot host an agent. This makes the CLI both the user-facing tool and a deployment smoke gate. Source: [src/cli.ts:220-340]() | Surface | Entry point | Primary consumer | Added in | |---|---|---|---| | `moryn` CLI | `src/cli.ts` | Developers, scripts | v0.1 | | `moryn-agent-smoke` | `src/cli.ts` | npm post-install hook | v0.1 | | `moryn dashboard` | `src/cli.ts` | Developers observing live agents | v0.1.1 | | MCP server | `src/mcp/server.ts` | MCP-compliant agents | v0.1 | | Host adapters | `src/core/host-adapters.ts` | Third-party agent runtimes | v0.1 | ## MCP Server Surface For agent-to-agent access, Moryn exposes a Model Context Protocol server defined in `src/mcp/server.ts`. The server binds to a local transport and advertises tools that map one-to-one onto Moryn's memory, skill, and handoff operations. Because the MCP layer delegates to the same core services the CLI uses, behavior — including identity attribution and lifecycle transitions — is identical regardless of whether the caller is a human or an agent. Source: [src/mcp/server.ts:1-180]() Input validation in the MCP server enforces the same agent-identity contract used elsewhere, rejecting requests that lack a registered identity or that attempt to act on another agent's namespace. This prevents cross-agent contamination when multiple agents share a single Moryn installation. Source: [src/mcp/server.ts:180-320]() ## Host Adapter Registry and Adapters Moryn is intentionally host-agnostic. Integration with concrete agent runtimes is mediated by an adapter contract in `src/core/host-adapters.ts` and a registry in `src/core/host-adapter-registry.ts`. The registry is consulted at startup; each registered adapter describes how Moryn discovers a host's agents, attaches to its event stream, and exposes store operations back to that host. Source: [src/core/host-adapters.ts:1-160]() The registry pattern keeps the core store portable. Adding a new agent platform requires only a new adapter module and a registration call — the memory, skill, and handoff layers remain untouched. Adapters emit lifecycle events that the dashboard can subscribe to, which is why the v0.1.1 observability view is able to reflect activity from heterogeneous hosts in a single window. Source: [src/core/host-adapter-registry.ts:1-140]() ## Agent Lifecycle and Identity Every command surface invocation is attributed to a stable agent identity created and managed by `src/core/agent-identity.ts`. An identity is minted on first registration, persisted locally, and reused across subsequent CLI calls and MCP requests so that memory writes, skill acquisitions, and handoffs are always attributable to a single agent. Source: [src/core/agent-identity.ts:1-180]() The lifecycle module (`src/core/agent-lifecycle.ts`) coordinates the transitions an agent moves through — registration, active work, handoff, quiescence — and emits events to subscribed adapters and to the dashboard. Lifecycle correctness is what allows `moryn-agent-smoke` to detect broken installations: if any transition fails, the smoke probe exits non-zero, and the npm post-install step surfaces the error to the integrator. Source: [src/core/agent-lifecycle.ts:1-220]() Together, these modules ensure that whether an agent is launched from the terminal, invoked through MCP, or hosted inside a third-party runtime, its interactions with Moryn's store are authenticated, attributable, and observable. --- ## Memory Lifecycle, Capture & Safety Model ### Related Pages Related topics: [Overview & System Architecture](#page-1), [Agent Integration & Command Surface](#page-2), [Dashboard, Sync & Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [src/core/capture-review.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/capture-review.ts) - [src/core/autocapture-policy.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/autocapture-policy.ts) - [src/core/capture-policy-report.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/capture-policy-report.ts) - [src/core/memory-lifecycle.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/memory-lifecycle.ts) - [src/core/memory-doctor.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/memory-doctor.ts) - [src/core/dogfood-report.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/dogfood-report.ts)
# Memory Lifecycle, Capture & Safety Model Moryn is a local-first memory, skill, and handoff layer for AI agents. The "Memory Lifecycle, Capture & Safety Model" describes how raw agent interactions enter the system, what gating logic decides whether they become persistent memories, and how that gating logic can be inspected, repaired, and audited over time. The model is implemented as a small set of cooperating modules under `src/core/`, each owning a single concern: policy evaluation, capture decisioning, lifecycle transitions, and reporting. ## Capture Policy and Autocapture Gating The capture pipeline is governed by an explicit policy object rather than implicit heuristics, which keeps the system predictable for agent developers. `autocapture-policy.ts` defines the ruleset used to decide whether a given transcript fragment should be promoted into the memory store. `capture-review.ts` consumes that policy and applies it to incoming content, returning a structured capture decision rather than silently mutating state. Source: [src/core/autocapture-policy.ts](); Source: [src/core/capture-review.ts](). A typical capture decision evaluates several dimensions: - **Source trustworthiness** — whether the producing agent or channel is recognized. - **Content classification** — whether the fragment is a preference, fact, skill cue, or throwaway chatter. - **Redaction rules** — whether secrets, credentials, or personally identifying tokens are present and must be stripped. - **Retention class** — whether the item is ephemeral, session-scoped, or durable. By centralizing these checks in one place, the policy can be tuned without rewriting downstream lifecycle code. Source: [src/core/capture-review.ts](). ## Memory Lifecycle States Once a fragment passes capture review, it enters the lifecycle managed by `memory-lifecycle.ts`. The lifecycle is a finite-state machine whose transitions are explicit and auditable. Items move from ingestion through validation, indexing, and either promotion to long-lived storage or eviction. The lifecycle report produced by this module is consumed both by the `moryn dashboard` (added in v0.1.1) and by the `memory-doctor` tool, giving operators a single source of truth for where each memory sits in the pipeline. Source: [src/core/memory-lifecycle.ts](); Source: [src/core/memory-doctor.ts](). | State | Purpose | Typical Exit | | --- | --- | --- | | Ingested | Raw capture accepted, awaiting validation | Validation pass or rejection | | Validated | Passed capture policy, not yet indexed | Indexing complete | | Active | Indexed and queryable by agents | Manual edit, expiry, or eviction | | Quarantined | Held for review due to policy violation | Manual resolution via doctor | | Evicted | Removed from active store | n/a (terminal) | Source: [src/core/memory-lifecycle.ts](). ## Safety Model and Inspection The safety model in Moryn is conservative by default: nothing is persisted unless the capture policy explicitly allows it, and anything ambiguous is routed through the review path rather than silently dropped. `capture-policy-report.ts` summarizes the active policy so developers can verify exactly which rules are live, which items were denied, and why. Source: [src/core/capture-policy-report.ts](). `memory-doctor.ts` is the operator-facing surface for this safety model. It exposes diagnostics for the lifecycle subsystem: it can list quarantined items, replay validation against the current policy, and surface inconsistencies between the captured record and the indexed form. Because the doctor operates on the same state machine the runtime uses, fixes applied through it are first-class lifecycle transitions rather than out-of-band edits. Source: [src/core/memory-doctor.ts](). ## Dogfood Reporting and Feedback Loop The closing piece of the model is `dogfood-report.ts`, which records how Moryn's own development workflow exercises the capture and lifecycle subsystems. Because Moryn is intended to be used by AI agents, the project runs internal workloads through the same capture policy and lifecycle machinery that end users will run, and the dogfood report makes the results inspectable. Source: [src/core/dogfood-report.ts](). This closes the loop: policy changes in `autocapture-policy.ts` are exercised by dogfood workloads, surfaced in `capture-policy-report.ts`, reasoned about in `memory-lifecycle.ts`, and repaired when needed via `memory-doctor.ts`. The `moryn dashboard` introduced in v0.1.1 makes each of these surfaces visible during agent work, which is the main user-facing improvement of that patch release. ## Practical Notes for Integrators - Treat the capture policy as the contract: if a memory type is not represented in `autocapture-policy.ts`, the capture reviewer will not produce it. - Prefer routing questionable content through the quarantine state and resolving it via the doctor rather than extending the policy ad hoc. - When debugging missing memories, start with `capture-policy-report.ts` to confirm what was rejected, then trace the surviving items through the lifecycle table above. - Watch the dogfood report when changing the policy; it is the cheapest signal that a tightening or relaxation has unintended consequences for normal agent workflows. Source: [src/core/capture-review.ts](); Source: [src/core/memory-lifecycle.ts](); Source: [src/core/memory-doctor.ts](). --- ## Dashboard, Sync & Operations ### Related Pages Related topics: [Overview & System Architecture](#page-1), [Agent Integration & Command Surface](#page-2), [Memory Lifecycle, Capture & Safety Model](#page-3)
Related Source Files The following source files were used to generate this page: - [src/observability/dashboard.ts](https://github.com/Richardyu114/Moryn/blob/main/src/observability/dashboard.ts) - [src/observability/dashboard-maintenance.ts](https://github.com/Richardyu114/Moryn/blob/main/src/observability/dashboard-maintenance.ts) - [src/core/replay.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/replay.ts) - [src/core/derived.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/derived.ts) - [src/core/config.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/config.ts) - [src/core/setup-wizard.ts](https://github.com/Richardyu114/Moryn/blob/main/src/core/setup-wizard.ts)
# Dashboard, Sync & Operations This page documents the operational surface of Moryn v0.1.1: the local observability dashboard introduced in the v0.1.1 patch release, the sync/replay machinery that keeps local stores consistent, and the configuration and setup-wizard entry points that operators use to bring a workspace online. ## Local Observability Dashboard Moryn v0.1.1 ships a `moryn dashboard` command that launches a local-first inspector for the active Moryn stores, added so that developers can validate memory, skill, and handoff state during agent work without leaving the terminal environment. The dashboard is implemented in `src/observability/dashboard.ts`, which owns the lifecycle of the inspector process and the data it reads from local storage. Source: [src/observability/dashboard.ts]() Maintenance of the dashboard's view of the stores — pruning stale entries, reconciling derived indexes, and refreshing cached projections — is handled in `src/observability/dashboard-maintenance.ts`. This module is responsible for the background upkeep tasks that keep the inspector responsive while the agent continues to write into the underlying stores. Source: [src/observability/dashboard-maintenance.ts]() Because the dashboard reads from local stores rather than a remote service, no credentials are required to inspect state, which aligns with Moryn's overall local-first design. ## Sync via Replay and Derived Stores Moryn's sync model is built on a replay pipeline that rebuilds derived state from the canonical event log of the local store. The replay module, located at `src/core/replay.ts`, iterates recorded events and applies them to downstream indexes so that consumers — including the dashboard — see a consistent view of memory, skill, and handoff artifacts. Source: [src/core/replay.ts]() Derived state, including projections used by the dashboard, is constructed in `src/core/derived.ts`. This module defines how raw store entries are transformed into the summaries, counts, and indexes that the dashboard surfaces and that other Moryn commands rely on for fast lookups. Source: [src/core/derived.ts]() The following diagram summarizes how the operational surface connects the dashboard to the underlying replay pipeline: ```mermaid flowchart LR A[Agent writes] --> B[Local event log] B --> C[replay.ts] C --> D[derived.ts projections] D --> E[dashboard.ts view] E --> F[Operator inspection] E --> G[dashboard-maintenance.ts upkeep] G --> D ``` Operationally, this means that restarting the dashboard or running `moryn dashboard` after a long agent session does not require a separate import step; the replay pipeline reconstructs the derived state on demand from the local log. ## Configuration Surface Runtime behavior of the dashboard, replay, and setup flows is governed by `src/core/config.ts`, which centralizes paths, store locations, and tunable parameters that the operator can adjust per workspace. Source: [src/core/config.ts]() The configuration module is the single source of truth that the dashboard reads when it decides where to open the local store, which derived indexes to materialize, and how aggressive maintenance tasks should be. Because the same config drives replay and derived-store construction, operators can change a parameter and see consistent behavior across the dashboard and the sync layer. ## First-Run and Setup Operations When Moryn is invoked in a fresh workspace, the setup wizard at `src/core/setup-wizard.ts` guides the operator through initializing the local store layout, default configuration values, and any environment prerequisites needed before the dashboard and sync layers can operate. Source: [src/core/setup-wizard.ts]() The wizard is intentionally idempotent: re-running it on an already-initialized workspace reports the existing state rather than overwriting it, which protects the event log that the replay pipeline depends on. ## Operator Workflow Summary A typical operator flow for the features covered on this page is: 1. Run `moryn` to enter the setup wizard on first use, which seeds the local store and configuration. Source: [src/core/setup-wizard.ts]() 2. Allow the agent to write into Moryn; events accumulate in the local log. Source: [src/core/replay.ts]() 3. Run `moryn dashboard` to inspect memory, skill, and handoff state via the derived projections. Source: [src/observability/dashboard.ts]() 4. Let `dashboard-maintenance.ts` reconcile and prune in the background so the inspector stays responsive. Source: [src/observability/dashboard-maintenance.ts]() ## Limitations and Scope These modules collectively cover local-first observability and sync only. They do not introduce a remote backend, authentication layer, or multi-host replication in v0.1.1; all state remains on the operator's machine. The dashboard is read-oriented — it inspects and maintains derived views but does not directly mutate the canonical event log, which keeps the replay pipeline as the sole writer of derived state. --- --- ## Pitfall Log Project: Richardyu114/Moryn Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification. ## 1. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/Richardyu114/Moryn ## 2. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/Richardyu114/Moryn ## 3. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/Richardyu114/Moryn ## 4. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/Richardyu114/Moryn ## 5. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/Richardyu114/Moryn ## 6. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/Richardyu114/Moryn ## 7. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/Richardyu114/Moryn