Related Pages

Related topics: Src

Overview

Pulse is a local-first, state-aware memory engine for AI agents. It ships as a monorepo combining an MCP (Model Context Protocol) server with a CLI application, designed to give agents durable, queryable memory that is shaped by the agent's current context rather than a flat similarity search. The project is published under the version line 0.6.x, with release 0.6.5 refining tag handling and security guards, and release 0.6.7 introducing state-aware capsule retrieval.

Purpose and Scope

The engine exists to solve a recurring problem with naive agent memory: most retrieval systems ignore *when* a memory is relevant and only consider *how similar* a stored item is to the present query. Pulse projects remembered items into a retrieval graph and layers a state channel on top, so that the agent's active context flags can decide WHICH memory wins, not just which one looks closest lexically.

The scope spans three layers:

• A storage layer that persists memory capsules locally (no external service required).
• A retrieval layer that combines lexical matching with thematic coherence and state-aware partitioning.
• A transport layer that exposes the engine to other agents through MCP, plus a developer-facing CLI for direct experimentation and smoke testing.

Source: README.md.

Component Layout

The repository is split into two top-level workspaces:

The pulse-app/ directory holds the CLI plus any companion tooling the MCP server depends on, keeping the server slim and the developer surface easy to invoke from a shell.

Source: mcp/README.md, pulse-app/README.md, pulse-app/cli/package.json.

Core Capabilities

• Local-first storage. Capsules are written and read from the local filesystem, so the engine works offline and avoids leaking agent state to third-party services.
• State-aware retrieval. Items tagged state:<flag> partition above the rest of the corpus while user_state.context_flags[flag] is active. Inside a flagged partition, a lexical tie-break picks the winner; when no flag is active, the engine falls back to state:calm plus thematic coherence. Release 0.6.7 measures this against a 15/15 retrieval suite.
• Unicode-aware memory tags. Tags accept non-ASCII input (e.g. Cyrillic) on the first validation attempt, removing a silent retry that previously added multi-second latency to pulse_remember. Source: pulse-app/cli/README.md.
• Negative-smoke security guards. Secret, path, and transcript guards reject all 15 dangerous payloads in the negative-smoke test matrix, ensuring that the engine cannot be tricked into persisting or retrieving hostile content.

Security Posture

Security is treated as a first-class feature rather than an afterthought. Every write path runs input through:

1. A secret guard that blocks tokens, keys, and credential-shaped strings.
2. A path guard that blocks filesystem traversal and absolute-path payloads.
3. A transcript guard that blocks raw dialogue fragments that could leak prior context.

These are exercised by a negative-smoke suite that explicitly enumerates the rejected payloads, so regressions surface immediately in CI rather than in production agents.

flowchart LR
    A[Agent call: pulse_remember] --> B{Input guards}
    B -->|reject| X[Refused payload]
    B -->|allow| C[Tag validation]
    C -->|Unicode non-ASCII| D[Accepted on first attempt]
    C -->|invalid| X
    D --> E[Local capsule store]
    E --> F[Retrieval graph]
    F --> G{State channel}
    G -->|flag active| H[state:flag partition]
    G -->|no flag| I[state:calm + thematic coherence]
    H --> J[Lexical tie-break]
    I --> J
    J --> K[Returned memory]

Source: pulse-app/cli/README.md, mcp/README.md.

Versioning and Release Cadence

Pulse follows a 0.6.x line with point releases that each ship a focused improvement:

• 0.6.5 — Unicode-aware memory tags; the silent retry on non-ASCII tags is removed; negative-smoke rejects all 15 dangerous payloads.
• 0.6.7 — State-aware capsule retrieval; remembered capsules are projected into the retrieval graph; a new state channel partitions state:<flag> items above the rest while user_state.context_flags[flag] is active; lexical tie-break inside the group; state:calm plus thematic coherence when no flag is active.

The cadence favours small, measurable increments so that retrieval quality can be evaluated against a stable benchmark between releases.

Source: pulse-app/cli/README.md, mcp/package.json.

Intended Audience

The primary readers of this Overview are:

• Agent authors integrating Pulse through MCP to give their agents persistent memory.
• Tooling developers extending the CLI or building harness scripts around the negative-smoke suite.
• Reviewers evaluating how state-aware retrieval differs from flat similarity search in production agents.

For deeper material, follow the component-specific pages linked from the mcp/ and pulse-app/cli/ directories.

Related Pages

Related topics: Overview, Src

Src

The src directory under mcp/ is the implementation home of Pulse's Model Context Protocol (MCP) server surface. It exposes the local-first, state-aware memory engine to MCP-compatible clients (Claude Desktop, IDE plugins, custom agents) over both stdio and HTTP transports. The directory follows a tight, test-saturated layout: every non-test module has a paired .test.ts file, which is consistent with the project's "negative-smoke" safety posture mentioned in the v0.6.5 release notes (15 dangerous payloads rejected). Source: mcp/src/index.ts:1-40.

Module Responsibilities

Source: mcp/src/index.ts:1-120, mcp/src/standalone.ts:1-80.

Entry Point and Tool Registration

index.ts is the canonical starting point referenced by the package's main field. It bootstraps the MCP server, attaches request handlers for Pulse's memory primitives, and routes inbound JSON-RPC messages. The handler set is what agents see as pulse_remember, retrieval, and state-flag mutations. The Unicode-aware tag validation added in v0.6.5 lives behind this handler surface, which is why the fix removed silent multi-second retries from pulse_remember. Source: mcp/src/index.ts:40-180.

The module also performs early guarding consistent with the project's secret/path/transcript guardrails. Inputs that match the negative-smoke patterns are rejected before they reach the storage layer, preserving the local-first guarantee. Source: mcp/src/index.ts:60-140.

Standalone Mode

standalone.ts lets Pulse be executed directly (pulse-mcp --standalone) without an enclosing agent host. It exposes the same tool surface as index.ts but bypasses framework-specific bindings. This is the mode used by integration tests and by users who want to drive Pulse from a custom client over stdio. Source: mcp/src/standalone.ts:1-60.

The paired standalone.test.ts verifies lifecycle invariants: process startup, handler registration, graceful shutdown on SIGTERM, and that the transport switches correctly when invoked with the --http flag. Source: mcp/src/standalone.test.ts:1-90.

HTTP Transport

http.test.ts exercises the HTTP transport layer, which is the alternative to stdio for agents that cannot spawn child processes. It asserts:

• Correct Content-Type and Mcp-Session-Id handling.
• JSON-RPC framing over POST /mcp.
• Proper HTTP status codes for malformed payloads and unsupported methods.
• That state-channel selection (introduced in v0.6.7) survives transport boundaries — state:<flag> tagged capsules must still partition above non-flagged items when user_state.context_flags[flag] is active on the wire. Source: mcp/src/http.test.ts:1-150.

Test Infrastructure and Safety Posture

The directory's test layout encodes the project's release contract. smoke_script.test.ts reproduces the v0.6.5 / v0.6.7 smoke harness: it runs the retrieval pipeline against curated fixtures and confirms 15/15 expected outcomes, including the negative-smoke rejection of the 15 dangerous payloads (secret exfiltration attempts, path traversal, transcript injection). Source: mcp/src/smoke_script.test.ts:1-200.

package_metadata.test.ts guards the publishable shape: it pins the package name, the bin entry that points to standalone.ts, the Node engine range, and the declared MCP SDK peer range. Drift in any of these fields fails the test, preventing accidental publishing of a package that an MCP host cannot load. Source: mcp/src/package_metadata.test.ts:1-80.

Architecture Flow

flowchart LR
  Agent[MCP Client / Agent] -->|JSON-RPC| Index[index.ts]
  Index --> Handlers[Tool Handlers]
  Handlers --> Engine[Memory Engine]
  Handlers -->|state:<flag>| State[State Channel]
  Engine --> Store[(Local Storage)]
  State --> Engine
  Index -.->|stdio| Agent
  Index -.->|HTTP| HttpT[http transport]
  Standalone[standalone.ts] --> Index

Source: mcp/src/index.ts:1-180, mcp/src/standalone.ts:1-60, mcp/src/http.test.ts:1-150.

Summary

mcp/src is intentionally small and test-dense. index.ts and standalone.ts define the two execution modes; the four .test.ts files collectively enforce the safety contract advertised in every release note (Unicode-aware tags, secret/path guards, state-aware retrieval ranking). Any change to tool handlers should be paired with an update to the corresponding smoke harness so the negative-smoke acceptance remains at 15/15. Source: mcp/src/smoke_script.test.ts:1-200, mcp/src/standalone.test.ts:1-90, mcp/src/package_metadata.test.ts:1-80.

Related Pages

Related topics: Src

Server

The internal/server package implements the HTTP surface of the Pulse memory engine. It is the boundary that turns client invocations (pulse_remember, retrieval, graph export, liveness probes) into calls against the underlying memory graph, and it is also where state-channel selection, tag validation, and secret/path guards are enforced before any capsule is written or projected. As Pulse 0.6.5 and 0.6.7 describe, this package is local-first and state-aware: requests carry a user_state.context_flags payload that drives retrieval, while safety checks reject dangerous payloads before they ever reach storage.

Role and Scope

The package wires the transport layer to the in-process memory engine. It owns:

• HTTP handlers for the public Pulse API (handlers.go).
• The state-channel continuity layer that decides which remembered capsule wins a retrieval (continuity.go, continuity_test.go).
• A graph export endpoint that serializes the retrieval graph (graph_export.go).
• A health endpoint used by orchestrators and smoke tests (health.go, health_test.go).

Source: pulse-app/internal/server/handlers.go:1-1

Scope is deliberately narrow: no business policy lives here beyond request shaping, validation, and projection. The package does not store capsules itself; it delegates to the engine and persists only what the engine approves.

Request Handling and Safety

handlers.go defines the entry points consumed by MCP-style clients. Each handler normalizes the inbound JSON, extracts the memory tag list, and runs the negative-smoke guard that rejects all 15 dangerous payload categories (secrets, absolute paths, transcript leakage). Tags are validated against a Unicode-aware regex so non-ASCII tags such as Cyrillic identifiers validate on the first attempt — a fix shipped in 0.6.5 to remove the silent retry that previously added multi-second latency to pulse_remember.

Source: pulse-app/internal/server/handlers.go:1-1

Source: pulse-app/internal/server/continuity_test.go:1-1

The same handler fan-out is exercised by continuity_test.go, which asserts that malformed tags, oversized payloads, and forbidden path segments never reach the storage layer. The negative-smoke regression is therefore co-located with the state-continuity tests because both paths share the same validation pipeline.

State-Aware Continuity

continuity.go projects remembered capsules into the retrieval graph and applies the state channel that 0.6.7 introduced. The rule is:

• Capsules tagged state:<flag> form a partition that is preferred while the corresponding user_state.context_flags[flag] is active.
• Inside that partition, a lexical tie-break resolves equal candidates.
• When no flag is active, items tagged state:calm win, falling back to thematic coherence.

Source: pulse-app/internal/server/continuity.go:1-1

The accompanying continuity_test.go pins this behaviour with deterministic fixtures: a 15/15 passing suite covering flag activation, lexical ordering, and the calm fallback. Because the channel sits inside the server package, the selection logic runs after the safety guards and before graph export, ensuring exported views respect the same partitioning clients observe.

Graph Export and Health

graph_export.go materializes the retrieval graph in a format suitable for inspection tools. The exporter reads the partitioned capsule set produced by the continuity layer, so a state:focus query and a default query can yield different subgraphs from the same store. The endpoint is read-only and inherits the same payload validation as the write path.

Source: pulse-app/internal/server/graph_export.go:1-1

health.go exposes a lightweight liveness probe used by smoke tests and orchestrators. It returns a stable response shape that health_test.go verifies, keeping the health contract independent of memory-engine upgrades. Together these two files keep operational concerns isolated from the retrieval pipeline.

Source: pulse-app/internal/server/health.go:1-1

Source: pulse-app/internal/server/health_test.go:1-1

Request Lifecycle

flowchart LR
    A[Client request] --> B[handlers.go<br/>decode + tag validation]
    B --> C{negative-smoke<br/>guards}
    C -- reject --> X[4xx error]
    C -- accept --> D[engine.remember / retrieve]
    D --> E[continuity.go<br/>state channel partition]
    E --> F[graph_export.go<br/>serialize view]
    F --> G[Response]
    E --> H[health.go<br/>liveness unaffected]

Source: pulse-app/internal/server/handlers.go:1-1

Source: pulse-app/internal/server/continuity.go:1-1

Source: pulse-app/internal/server/graph_export.go:1-1

Source: pulse-app/internal/server/health.go:1-1

The lifecycle makes the package's contract explicit: validation first, engine call second, continuity projection third, export last, with health running on an independent path. Any change to the state channel in continuity.go therefore flows through both retrieval responses and graph exports without separate wiring.

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/zbs-gg/pulse

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/zbs-gg/pulse

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/zbs-gg/pulse

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/zbs-gg/pulse

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/zbs-gg/pulse

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/zbs-gg/pulse

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/zbs-gg/pulse

Community Discussion Evidence

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

• v0.6.7 — state-aware capsule retrieval - github / github_release
• Pulse 0.6.5 - github / github_release
• Configuration risk requires verification - GitHub / issue