# https://github.com/VineetV2/peon-mem Project Manual

Generated at: 2026-07-22 00:11:40 UTC

## Table of Contents

- [Introduction to Peon](#page-introduction)
- [Architecture, Daemon, and MCP Infrastructure](#page-architecture)
- [Memory Model, Consolidation, and Retrieval](#page-memory-retrieval)
- [Agent Integration, Deployment, Monitoring, and Evaluation](#page-integration-operations)

<a id='page-introduction'></a>

## Introduction to Peon

### Related Pages

Related topics: [Architecture, Daemon, and MCP Infrastructure](#page-architecture)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/VineetV2/peon-mem/blob/main/README.md)
- [src/index.ts](https://github.com/VineetV2/peon-mem/blob/main/src/index.ts)
- [src/types.ts](https://github.com/VineetV2/peon-mem/blob/main/src/types.ts)
- [src/config.ts](https://github.com/VineetV2/peon-mem/blob/main/src/config.ts)
- [package.json](https://github.com/VineetV2/peon-mem/blob/main/package.json)
</details>

# 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:

| Layer | File | Responsibility |
|-------|------|----------------|
| Public API | `src/index.ts` | Re-exports the public functions and types that consumers interact with |
| Type contracts | `src/types.ts` | Declares the shapes of memory records, queries, and configuration options |
| Runtime configuration | `src/config.ts` | Resolves defaults, environment overrides, and file-based settings |

`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]()`.

```mermaid
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]()`.

---

<a id='page-architecture'></a>

## Architecture, Daemon, and MCP Infrastructure

### Related Pages

Related topics: [Introduction to Peon](#page-introduction), [Memory Model, Consolidation, and Retrieval](#page-memory-retrieval), [Agent Integration, Deployment, Monitoring, and Evaluation](#page-integration-operations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/daemon.ts](https://github.com/VineetV2/peon-mem/blob/main/src/daemon.ts)
- [src/daemon-cli.ts](https://github.com/VineetV2/peon-mem/blob/main/src/daemon-cli.ts)
- [src/brain.ts](https://github.com/VineetV2/peon-mem/blob/main/src/brain.ts)
- [src/tools.ts](https://github.com/VineetV2/peon-mem/blob/main/src/tools.ts)
- [src/index.ts](https://github.com/VineetV2/peon-mem/blob/main/src/index.ts)
- [bin/peon-mem.mjs](https://github.com/VineetV2/peon-mem/blob/main/bin/peon-mem.mjs)
</details>

# 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]().

| Layer | File | Role |
|---|---|---|
| Launcher | `bin/peon-mem.mjs` | Node entry script that boots the TS runtime |
| MCP bootstrap | `src/index.ts` | Constructs the MCP server and registers tools |
| Public tool surface | `src/tools.ts` | Declarative list of MCP tools and their handlers |
| Domain logic | `src/brain.ts` | Memory/cognition operations invoked by tools |
| Background service | `src/daemon.ts` | Long-lived process for stateful or asynchronous work |
| Operator CLI | `src/daemon-cli.ts` | Commands to start, query, or stop the daemon |

## 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]().

```mermaid
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.

---

<a id='page-memory-retrieval'></a>

## Memory Model, Consolidation, and Retrieval

### Related Pages

Related topics: [Architecture, Daemon, and MCP Infrastructure](#page-architecture), [Agent Integration, Deployment, Monitoring, and Evaluation](#page-integration-operations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/memory-store.ts](https://github.com/VineetV2/peon-mem/blob/main/src/memory-store.ts)
- [src/memory-mutations.ts](https://github.com/VineetV2/peon-mem/blob/main/src/memory-mutations.ts)
- [src/processor.ts](https://github.com/VineetV2/peon-mem/blob/main/src/processor.ts)
- [src/retrieval.ts](https://github.com/VineetV2/peon-mem/blob/main/src/retrieval.ts)
- [src/reranker.ts](https://github.com/VineetV2/peon-mem/blob/main/src/reranker.ts)
- [src/hyde.ts](https://github.com/VineetV2/peon-mem/blob/main/src/hyde.ts)
</details>

# 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.

| Stage | Module | Responsibility |
|---|---|---|
| Ingest | `processor.ts` | Parse, chunk, embed, classify |
| Persist | `memory-mutations.ts` + `memory-store.ts` | Apply create/update/merge/delete atomically |
| Query expand | `hyde.ts` | Hypothetical-document embedding for recall |
| Search | `retrieval.ts` + `memory-store.ts` | Vector lookup, candidate gathering |
| Rerank | `reranker.ts` | Re-score top-k for precision |

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]().

---

<a id='page-integration-operations'></a>

## Agent Integration, Deployment, Monitoring, and Evaluation

### Related Pages

Related topics: [Architecture, Daemon, and MCP Infrastructure](#page-architecture), [Memory Model, Consolidation, and Retrieval](#page-memory-retrieval)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [scripts/claude-peon-hook.mjs](https://github.com/VineetV2/peon-mem/blob/main/scripts/claude-peon-hook.mjs)
- [scripts/codex-peon-hook.mjs](https://github.com/VineetV2/peon-mem/blob/main/scripts/codex-peon-hook.mjs)
- [src/injection.ts](https://github.com/VineetV2/peon-mem/blob/main/src/injection.ts)
- [src/monitor.ts](https://github.com/VineetV2/peon-mem/blob/main/src/monitor.ts)
- [src/token-ab-monitor.ts](https://github.com/VineetV2/peon-mem/blob/main/src/token-ab-monitor.ts)
- [scripts/token-ab-monitor.html](https://github.com/VineetV2/peon-mem/blob/main/scripts/token-ab-monitor.html)
</details>

# 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

| Layer | Component | File |
|---|---|---|
| Agent entry (Claude) | Claude hook script | `scripts/claude-peon-hook.mjs` |
| Agent entry (Codex) | Codex hook script | `scripts/codex-peon-hook.mjs` |
| Core | Context injection | `src/injection.ts` |
| Observability | General runtime monitor | `src/monitor.ts` |
| Observability | Token A/B monitor | `src/token-ab-monitor.ts` |
| UI | A/B experiment dashboard | `scripts/token-ab-monitor.html` |

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.

---

<!-- evidence_pipeline_checked: true -->

---

## Pitfall Log

Project: VineetV2/peon-mem

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

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

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

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

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

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

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

<!-- canonical_name: VineetV2/peon-mem; human_manual_source: deepwiki_human_wiki -->