Related Pages

Related topics: Architecture, Daemon, and MCP Infrastructure

Introduction to Peon

Peon is a TypeScript-based project that provides a structured, persistent memory layer designed to be consumed by AI agents and developer tooling. The repository is named peon-mem, indicating that the core deliverable is a "memory" subsystem that records, indexes, and retrieves contextual information across agent sessions. The project is published as an installable npm package, exposes a programmatic entry point through src/index.ts, and defines its public surface area using the type declarations in src/types.ts and runtime configuration in src/config.ts Source: package.json:1-40 Source: src/index.ts:1-30.

Project Goals and Scope

According to the project description in README.md, Peon exists to give AI assistants and automation scripts a stable, queryable store of past decisions, observations, and context snippets that would otherwise be lost between invocations. Rather than treating each conversation as ephemeral, Peon persists structured records so that downstream agents can resume reasoning with prior knowledge. The scope is intentionally narrow: it is a memory substrate, not a general-purpose database or vector store, and it favors a minimal API so it can be embedded in different runtimes Source: README.md:1-60.

The package configuration confirms that the project targets a modern Node.js environment and ships ESM-compatible TypeScript Source: package.json:1-40. The main, module, and types fields in package.json point at compiled artifacts that re-export the contents of src/index.ts, making it the canonical public entry point for both programmatic and CLI usage Source: src/index.ts:1-30.

High-Level Architecture

The codebase follows a small, conventional layered structure:

src/index.ts acts as the single import surface, aggregating the modules so that downstream code can write a single import rather than reaching into internal paths Source: src/index.ts:1-30. src/types.ts is the authoritative reference for the data model: any record stored in Peon conforms to the interfaces declared there, and any consumer code that wants type-safe access should import its types from this module rather than redefining them locally Source: src/types.ts:1-80. src/config.ts centralizes defaults such as storage location, retention rules, and feature toggles so that behavior is consistent regardless of how Peon is invoked Source: src/config.ts:1-60.

graph TD
    A[Consumer / Agent] -->|import| B(src/index.ts)
    B --> C[src/types.ts]
    B --> D[src/config.ts]
    D -->|reads| E[Environment / File Config]
    C -->|shapes| F[Memory Records]
    D --> F
    F -->|persisted| G[(Storage Backend)]

Typical Usage Pattern

From a consumer's perspective, working with Peon follows three steps described in the README. First, the package is installed and the entry point is imported. Second, the consumer creates or opens a memory namespace, optionally passing configuration values that override the defaults defined in src/config.ts. Third, the consumer issues store and retrieve operations against that namespace, with results returned as strongly typed objects matching the interfaces in src/types.ts Source: README.md:30-120 Source: src/index.ts:10-50.

Because src/types.ts is the single source of truth for record shapes, any evolution of the memory schema is expected to be reflected there first. Consumers who pin their dependency to a specific Peon version can rely on the exported types to catch breaking changes at compile time rather than at runtime Source: src/types.ts:1-80.

Configuration and Extensibility

Configuration is intentionally separated from logic. src/config.ts defines a loadConfig style entry that merges defaults, environment variables, and any caller-supplied overrides into a single resolved configuration object Source: src/config.ts:1-60. This separation means that operational concerns such as changing the storage path or enabling a feature flag do not require code changes to the public API exposed in src/index.ts. The README documents the supported environment variables and file locations that src/config.ts understands Source: README.md:60-140.

Summary

Peon is a focused memory layer for AI agents and automation scripts, delivered as a TypeScript npm package. Its architecture is intentionally small: a public entry point in src/index.ts, a type contract in src/types.ts, and a configuration module in src/config.ts, all described to users through README.md and wired together via package.json. This minimal surface area makes it straightforward to embed, while the strict typing and centralized configuration keep the contract between Peon and its consumers stable as the project evolves Source: README.md:1-60 Source: package.json:1-40 Source: src/index.ts:1-30 Source: src/types.ts:1-80 Source: src/config.ts:1-60.

Related Pages

Related topics: Introduction to Peon, Memory Model, Consolidation, and Retrieval, Agent Integration, Deployment, Monitoring, and Evaluation

Architecture, Daemon, and MCP Infrastructure

1. Purpose and Scope

peon-mem is a Model Context Protocol (MCP) server that exposes a memory/cognition service to MCP-compatible clients. The "Architecture, Daemon, and MCP Infrastructure" topic covers the structural skeleton that makes this possible: how the process starts, how the MCP transport is wired, how tools are registered, and how a separate daemon process supports work that must outlive a single tool call.

The codebase splits this responsibility across six files. The split keeps three concerns independent: the protocol-facing surface (what clients can call), the long-running service layer (state that persists), and the domain logic (the actual memory operations). Source: src/index.ts, src/daemon.ts, src/brain.ts.

2. Process Bootstrap and Module Topology

The entry chain is short and explicit. bin/peon-mem.mjs is the executable Node script that launches the runtime; from there, src/index.ts is the TypeScript module that constructs the MCP server, registers transports, and attaches the tool handlers. Source: bin/peon-mem.mjs, src/index.ts.

The src/tools.ts module exports the tool surface — the list of MCP-callable functions, their parameter schemas, and the handler functions that bridge a client request to the rest of the system. src/index.ts consumes this list and wires each tool into the active MCP transport, so adding a new capability is a matter of extending src/tools.ts rather than touching transport code. Source: src/tools.ts, src/index.ts.

src/brain.ts is the cognitive core: the module the tool handlers ultimately delegate to. It encapsulates the domain logic for memory operations and is the single source of truth for what those tools actually do. Source: src/tools.ts, src/brain.ts.

3. The Daemon Subsystem

Not every piece of work belongs in a synchronous tool handler. src/daemon.ts defines a separate long-running process that holds persistent state, performs background indexing, or services requests that exceed a tool call's reasonable lifetime. Because it lives in its own process, it survives the MCP request that triggered it and can be reused across many calls. Source: src/daemon.ts.

src/daemon-cli.ts is the companion CLI surface for this process. It exposes commands an operator (or a wrapper script invoked by a tool handler) can run to start the daemon, inspect its status, or shut it down. Keeping process management in its own module — rather than inside src/index.ts or src/tools.ts — means the MCP request path stays free of fork/exec plumbing, and operator workflows do not depend on an MCP transport being active. Source: src/daemon-cli.ts, src/daemon.ts.

flowchart LR
  Client[MCP Client] -->|tool call| Index[src/index.ts]
  Index --> Tools[src/tools.ts]
  Tools --> Brain[src/brain.ts]
  Tools -. offload .-> Daemon[src/daemon.ts]
  Daemon <-->|CLI| DaemonCli[src/daemon-cli.ts]
  Bin[bin/peon-mem.mjs] --> Index

4. Boundaries and Extension Points

The architecture enforces a clean separation between four concerns:

• Transport lives in src/index.ts; it should not embed domain logic.
• Tool surface lives in src/tools.ts; it is declarative and thin.
• Domain logic lives in src/brain.ts; both tools and the daemon may import it.
• Process management lives in src/daemon.ts and src/daemon-cli.ts; the MCP server consumes it as a service rather than as code in its own process. Source: src/brain.ts, src/daemon.ts, src/daemon-cli.ts, src/tools.ts, src/index.ts.

To extend the system, a developer typically adds a new tool definition in src/tools.ts, places its behavior in src/brain.ts, and — only if the operation is genuinely long-lived — surfaces a daemon command in src/daemon-cli.ts for a backing service in src/daemon.ts. The launcher bin/peon-mem.mjs is unaffected, and existing tools continue to work unchanged. This separation is what keeps the MCP-facing surface small, the cognitive core testable, and the daemon operationally independent.

Related Pages

Related topics: Architecture, Daemon, and MCP Infrastructure, Agent Integration, Deployment, Monitoring, and Evaluation

Memory Model, Consolidation, and Retrieval

Overview

The peon-mem project implements a long-term memory subsystem that ingests input, consolidates it into structured memory records, and retrieves relevant context on demand. The subsystem is split across six cooperating modules: a persistence layer (memory-store.ts), a mutation surface (memory-mutations.ts), an ingestion/processing pipeline (processor.ts), and a retrieval pipeline composed of retrieval.ts, hyde.ts, and reranker.ts. Together they form two cooperating paths: a write path (processor → mutations → store) and a read path (retrieval → hyde → store → reranker). Source: src/memory-store.ts:1-40, src/processor.ts:1-30, src/retrieval.ts:1-30.

Memory Model and Storage

The memory model is centered on discrete memory records persisted by the store module. memory-store.ts defines the schema for a memory unit — typically an identifier, a content body, an embedding vector, timestamps, and metadata such as source type or scope — and exposes the CRUD-style operations used by every other module. Because both read and write paths go through it, the store is the single source of truth for memory state. Source: src/memory-store.ts:40-120.

Embeddings are co-located with records rather than offloaded to a separate vector service, which keeps the basic retrieval path self-contained. Record lifecycles (active, superseded, deleted) are tracked through metadata fields on the same record, so the mutation layer never needs to coordinate across multiple tables to update a memory's status. Source: src/memory-store.ts:120-200.

Consolidation: Processor and Mutations

Consolidation is the process of turning raw input into persistent, deduplicated memory records. The processor.ts module handles ingestion: it parses incoming content, optionally chunks it, generates embeddings, and classifies each piece as novel, an update to an existing memory, or a duplicate. It is responsible for the *policy* of consolidation — when to merge, when to supersede, when to ignore. Source: src/processor.ts:30-150.

The memory-mutations.ts module exposes the verbs that actually apply changes against the store: create, update, merge, and delete. It is intentionally thin: its job is to guarantee that whatever the processor decides is applied atomically and that downstream invariants (uniqueness, embedding freshness, referential integrity) hold. Splitting policy from mechanism this way lets the processor implement richer behaviors — similarity thresholds, time decay, importance scoring — without bypassing safety checks. Source: src/memory-mutations.ts:1-80.

When the processor detects semantic overlap with an existing record, it issues an update or merge rather than a create, preventing the store from filling with near-duplicates. Each mutation returns a result that the caller can log or surface to a user-facing notification stream, and the store updates its index in the same call so subsequent reads see the new state immediately. Source: src/processor.ts:150-260, src/memory-mutations.ts:80-160.

Retrieval: HyDE, Search, and Re-ranking

The read path begins in retrieval.ts, which accepts a query and orchestrates search. The first stage rewrites the query using the HyDE (Hypothetical Document Embeddings) strategy in hyde.ts: instead of embedding the raw question, the module prompts a model to produce a hypothetical answer passage and embeds *that* instead, then uses the resulting vector to look up similar real memories. This typically improves recall when the query wording is semantically distant from the answer style stored in memory. Source: src/hyde.ts:1-100, src/retrieval.ts:30-90.

Candidate memories returned by vector lookup against the store are then passed to reranker.ts, which applies a more expensive but more accurate cross-attention or LLM-based scoring pass over the top-k results. The reranker promotes records that are truly relevant to the query and demotes those that are merely surface-similar. The final ranked list — along with score metadata — is returned to the caller. Source: src/reranker.ts:1-120, src/retrieval.ts:90-160.

End-to-End Data Flow

A typical write flow: input enters processor.ts, is classified, and is committed via memory-mutations.ts into memory-store.ts. A typical read flow: a query enters retrieval.ts, is expanded via hyde.ts, is used to fetch candidate vectors from memory-store.ts; candidates are reranked by reranker.ts and returned.

This decomposition keeps each concern testable in isolation while memory-store.ts remains the only shared dependency between write and read paths. Adding a new consolidation rule therefore touches only the processor, and adding a new retrieval signal touches only retrieval/hyde/reranker — the store contract stays stable. Source: src/memory-store.ts:1-40, src/processor.ts:1-30, src/retrieval.ts:1-30, src/memory-mutations.ts:1-80, src/hyde.ts:1-100, src/reranker.ts:1-120.

Related Pages

Related topics: Architecture, Daemon, and MCP Infrastructure, Memory Model, Consolidation, and Retrieval

Agent Integration, Deployment, Monitoring, and Evaluation

The peon-mem project acts as a memory-augmented layer that sits between external AI coding agents and their underlying models. Its agent-integration, deployment, monitoring, and evaluation story is implemented across two complementary halves: executable hook scripts under scripts/ that adapt agent-specific protocols, and TypeScript modules under src/ that implement the shared runtime, injection logic, and observability.

Agent Integration

Peon-mem is designed to be invoked by the agent itself, not by the user directly. Each supported agent has its own thin entry script that translates the agent's protocol into peon-mem's internal calls.

Claude Integration

The Claude agent talks to peon-mem through scripts/claude-peon-hook.mjs. This script is the integration point that receives Claude tool events and forwards them into the peon-mem runtime so that the agent can consult and persist memory entries between turns. Source: scripts/claude-peon-hook.mjs

Codex Integration

Codex is wired in through a sibling script, scripts/codex-peon-hook.mjs. Maintaining a dedicated hook per agent keeps agent-specific event shapes and lifecycle quirks isolated from the shared core, and means that adding a new agent only requires a new adapter rather than changes to the memory pipeline. Source: scripts/codex-peon-hook.mjs

Context Injection Core

Once a hook has translated an event, the request reaches the core injection module in src/injection.ts. This module is responsible for shaping stored memory items into the prompt context that the agent ultimately consumes. Because both the Claude and Codex hooks delegate to this single module, ranking, formatting, and truncation rules for memory are defined once and reused across agents. Source: src/injection.ts

Deployment

Deployment follows the same split as the source layout. The .mjs hooks in scripts/ are intended to be launched by the host agent as part of its tool-call lifecycle, acting as lightweight Node entry points. The TypeScript modules under src/ are compiled into the runtime that those hooks import, so heavy logic (memory lookup, injection formatting, monitoring) lives in the compiled core while each agent only pays the cost of a small adapter process. Source: scripts/claude-peon-hook.mjs, scripts/codex-peon-hook.mjs, src/injection.ts

This layered deployment is what allows the same memory and monitoring machinery to serve multiple agents without forking the codebase per integration.

Monitoring

Two monitors provide observability for the system.

General Runtime Monitor

src/monitor.ts is the general-purpose monitor. It records signals such as injection invocations, hook events, and any errors raised while constructing context, giving operators a way to confirm that the integration is functioning end-to-end for both Claude and Codex. Source: src/monitor.ts

Token A/B Monitor

To evaluate the cost impact of memory injection, peon-mem ships a dedicated A/B monitor in src/token-ab-monitor.ts. This module compares token consumption between runs with memory injection enabled and a control variant, recording the deltas. The recorded metrics are surfaced through a companion dashboard, scripts/token-ab-monitor.html, where operators can inspect experiment results interactively. Source: src/token-ab-monitor.ts, scripts/token-ab-monitor.html

Evaluation Workflow

The intended evaluation loop ties the monitors and the hooks together:

1. Launch an agent session with the appropriate peon-mem hook attached.
2. Capture per-run signals through the general monitor in src/monitor.ts.
3. Toggle the A/B configuration via the token monitor to alternate between memory-on and memory-off variants.
4. Inspect the resulting token deltas in scripts/token-ab-monitor.html to decide whether the memory layer is worth its prompt-cost overhead.

This loop lets maintainers reason about injection quality and token efficiency without altering the underlying agent's behaviour. Source: src/monitor.ts, src/token-ab-monitor.ts, scripts/token-ab-monitor.html

Architecture at a Glance

The design pushes agent-specific protocol handling to the edges (the hook scripts) and concentrates shared logic — memory injection, monitoring, and evaluation — in reusable core modules, which is what makes the system easy to extend with new agents or new measurement dimensions.

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/VineetV2/peon-mem

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/VineetV2/peon-mem

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/VineetV2/peon-mem

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/VineetV2/peon-mem

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/VineetV2/peon-mem

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/VineetV2/peon-mem

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/VineetV2/peon-mem

Community Discussion Evidence

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

• Configuration risk requires verification - GitHub / issue