@atrib/recall 0.12.15 → 0.12.17

package/README.md

@@ -77,7 +77,7 @@ Every call to this tool (and every sibling tool below) writes a per-call jsonl e
 
 - `mcp__atrib-recall__recall_revisions({ record_hash })` - returns the forward revision chain for the target record. Each chain entry carries `record_hash`, `timestamp`, and the [D086](../../DECISIONS.md#d086-bm25-corpus-extended-from-annotations-to-per-event_type-record-content)-normative content fields (`new_position`, `reason`, `importance`) when present, so the agent can read the chain inline without follow-up `recall` calls per revision. The chain follows the first-by-timestamp revision at each step; when more than one revision targets the same record (sibling fan-out, common in multi-agent flows), the other branch heads are listed on that step's entry as `sibling_hashes`, so the agent can recursively call `recall_revisions` on a sibling to traverse a parallel branch instead of having to manually enumerate revisions via `recall_my_attribution_history`.
 
-- `mcp__atrib-recall__recall_by_content({ query, k? })` - BM25 free-form retrieval over each record's indexable text + the annotation summary + topic_tags (when present), then reranked by Park et al. weighted-sum scoring (recency + importance + relevance). Default k=10, max 50. Per [D086](../../DECISIONS.md#d086-bm25-corpus-extended-from-annotations-to-per-event_type-record-content), "indexable text" is per-event_type record content from the [D062](../../DECISIONS.md#d062-local-mirror-sidecar-two-tier-private-local--public-canonical-persistence) sidecar (observation: `what + why_noted + topics`; tool_call: `tool_name + args excerpt + result excerpt`; annotation: `summary + topics`; revision: `prior_position + new_position + reason + topics`; transaction: counterparty + memo + protocol fields; directory_anchor: `tree_root + epoch_id`). Extension URIs fall back to a generic recursive string-walk (depth ≤ 4, field cap 2KB). OpenInference local sidecars add recall tokens for span kind/name, tool/agent/model, prompt identifiers and templates, inputs/outputs, usage, cost, score, and metadata when those fields are mirrored locally per [D108](../../DECISIONS.md#d108-observability-span-trees-are-intake-local-sidecars-are-cognitive-payload). BM25 contribution is clamped to [0, 1] in the parkScore site so the documented Park-component bound is honored. Layer 2 (sqlite-vec sidecar, separate ship) extends with embedding similarity over the same indexed text.
+- `mcp__atrib-recall__recall_by_content({ query, k? })` - BM25 free-form retrieval over each record's indexable text + the annotation summary + topic_tags (when present), then reranked by Park et al. weighted-sum scoring (recency + importance + relevance). Default k=10, max 50. Per [D086](../../DECISIONS.md#d086-bm25-corpus-extended-from-annotations-to-per-event_type-record-content) and [D118](../../DECISIONS.md#d118-primary-trace-path-is-a-presentation-rule-over-trace-and-chain), "indexable text" is per-event_type record content from the [D062](../../DECISIONS.md#d062-local-mirror-sidecar-two-tier-private-local--public-canonical-persistence) sidecar (observation: `what + why_noted + intent + rationale + topics`; tool_call: `tool_name + args excerpt + result excerpt`; annotation: `summary + topics`; revision: `prior_position + new_position + reason + topics`; transaction: counterparty + memo + protocol fields; directory_anchor: `tree_root + epoch_id`). Extension URIs fall back to a generic recursive string-walk (depth ≤ 4, field cap 2KB). OpenInference local sidecars add recall tokens for span kind/name, tool/agent/model, prompt identifiers and templates, inputs/outputs, usage, cost, score, and metadata when those fields are mirrored locally per [D108](../../DECISIONS.md#d108-observability-span-trees-are-intake-local-sidecars-are-cognitive-payload). BM25 contribution is clamped to [0, 1] in the parkScore site so the documented Park-component bound is honored. Layer 2 (sqlite-vec sidecar, separate ship) extends with embedding similarity over the same indexed text.
 
 - `mcp__atrib-recall__recall_session_chain({ context_id?, limit?, include_content? })` - returns all records in a context_id, ordered chronologically (oldest-first). The natural traversal of the CHAIN_PRECEDES topology for a single session/trace. Each entry carries `record_hash`, `event_type`, `timestamp`, `display_summary`, `display_producer`, `age`, plus signed causal/tool fields when present (`informed_by`, `tool_name`, `args_hash`, `result_hash`). When `include_content` is true, each entry also includes the [D062](../../DECISIONS.md#d062-local-mirror-sidecar--two-tier-private-local--public-canonical-persistence) local mirror body as `local_content` and the local producer label as `local_producer`. Defaults false to keep the session chain cheap. When `context_id` is omitted, falls back to `resolveEnvContextId` (the same precedence as the other tools: `ATRIB_CONTEXT_ID` env, then a [D083](../../DECISIONS.md#d083-harness-session-id-discovery-extends-d078-for-cognitive-primitive-mcp-servers)-registered harness env like `CLAUDE_CODE_SESSION_ID`).
 
@@ -165,5 +165,5 @@ Or run via `npx`:
 ## What this does NOT do
 
 - **No log-inclusion verification.** Local signature verification ≠ log commitment proof. Use the log API for inclusion proofs.
-- **No graph derivation.** Returns records, not the [§3.2.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#324-edge-derivation-rules) graph. For that, use `@atrib/trace` (causal chain) or query graph-node directly.
+- **No graph derivation.** Returns records, not the [§3.2.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#324-edge-derivation-rules) graph. For declared-relationship walks, use `@atrib/trace`; for graph projections, query graph-node directly.
 - **No write surface.** Read-only. Use `@atrib/emit` to sign new records.

package/dist/index.d.ts

@@ -1,4 +1,36 @@
 #!/usr/bin/env node
+/**
+ * @atrib/recall - local signed-record recall MCP server.
+ *
+ * Exposes the base recall tool plus sibling query-shape tools to the host agent.
+ * Reads signed-record jsonl mirrors (per spec §5.9), VERIFIES the Ed25519
+ * signature on each record before returning it, and tags every entry with
+ * signature_verified so the agent can distinguish provable past from tampered
+ * or partial mirror state.
+ *
+ * Mirror discovery (in priority order):
+ *   1. ATRIB_RECORD_FILE - single explicit jsonl file. Back-compat with
+ *      pre-0.4.0 callers that pinned a specific producer's mirror.
+ *   2. ATRIB_MIRROR_DIR - directory; recall reads every `*.jsonl` inside.
+ *      Default: ~/.atrib/records (the spec §5.9 well-known mirror namespace).
+ *
+ * Two on-disk shapes are accepted, matching D062 / spec §5.9:
+ *   - Bare AtribRecord (legacy producers):           {spec_version, ...}
+ *   - Envelope (D062 sidecar form):                  {record: {...}, proof?, _local?}
+ * Both round-trip through verifyRecord; the parser picks the right inner shape.
+ *
+ * Trust scope: signature verification is local-only. A passing signature_verified
+ * proves the record was signed by the named creator_key; it does NOT prove the
+ * record was committed to log.atrib.dev. To confirm log inclusion, the caller
+ * should fetch the inclusion proof from the log API.
+ *
+ * Configuration via environment variables:
+ *   ATRIB_RECORD_FILE - single explicit file (overrides directory scan).
+ *   ATRIB_MIRROR_DIR - directory to scan. Default: ~/.atrib/records.
+ *   ATRIB_LOG_ORIGIN - origin used in human-readable messages.
+ *                        Default: log.atrib.dev
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AtribRecord, EventTypeShortName } from '@atrib/mcp';
 export type ImportanceLabel = 'critical' | 'high' | 'medium' | 'low' | 'noise';
 export declare const IMPORTANCE_NUMERIC: Record<ImportanceLabel, number>;
@@ -277,4 +309,9 @@ export declare function discoverRecords(recordFile?: string): {
     files: string[];
 };
 export declare function recall(args: RecallArgs, recordFile?: string): Promise<RecallResult>;
+export interface AtribRecallServer {
+    mcp: McpServer;
+}
+export declare function registerAtribRecallTools(server: McpServer): void;
+export declare function createAtribRecallServer(): AtribRecallServer;
 export {};