Related Pages

Related topics: Agent Integration & Command Surface, Memory Lifecycle, Capture & Safety Model, Dashboard, Sync & Operations

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.

flowchart TB
    CLI["CLI Layer<br/>moryn / moryn dashboard"]
    Engine["Engine Layer<br/>src/core/engine.ts"]
    Store["Store Layer<br/>src/core/store.ts"]
    Schema["Schema & Types<br/>src/core/schema.ts, types.ts"]
    Disk[("Local<br/>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

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

Related Pages

Related topics: Overview & System Architecture, Memory Lifecycle, Capture & Safety Model

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

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.

Related Pages

Related topics: Overview & System Architecture, Agent Integration & Command Surface, Dashboard, Sync & Operations

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.

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.

Related Pages

Related topics: Overview & System Architecture, Agent Integration & Command Surface, Memory Lifecycle, Capture & Safety Model

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:

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.

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Richardyu114/Moryn

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Richardyu114/Moryn

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Richardyu114/Moryn

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Richardyu114/Moryn

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Richardyu114/Moryn

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Richardyu114/Moryn

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Richardyu114/Moryn

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using Moryn with real data or production workflows.

• Moryn v0.2.0 - github / github_release
• Moryn v0.1.1 - github / github_release
• Moryn v0.1 - github / github_release
• Configuration risk requires verification - GitHub / issue