AgentSpine — identity that persists, memory that stays grounded

CI status Apache-2.0 license Node.js 20.9 or newer Source documents are read-only

A local-first, host-neutral context spine for agents that already have a history.

AgentSpine discovers the Markdown files an agent already relies on, fingerprints them, preserves the host's native hierarchy, follows explicit links, and serves only the relevant context through a CLI, lifecycle hooks, and MCP. It does **not** replace your agent. It gives existing identity and memory a dependable structure without rewriting a single source byte. ## Why AgentSpine Most agent memory systems begin by asking you to migrate everything into a new database or a new canonical file. AgentSpine begins with a stricter promise: > Your existing `SOUL.md`, `AGENTS.md`, `CLAUDE.md`, `MEMORY.md`, and linked Markdown remain where they are, exactly as they are. That makes AgentSpine suitable for long-lived agents, mixed Claude Code/Codex environments, repositories with nested instruction files, and teams that cannot afford silent identity drift. ## How it fits together ```mermaid flowchart TB A["Existing Markdown sources"] --> B["Read-only discovery"] B --> C["Provenance catalog"] C --> D["Host-aware resolver"] F["Relationships + attention + safe learning + tasks + reviewed sharing"] --> G["Budgeted session briefing"] D --> G P["Separate default-deny delegation policy"] --> F Y["Exact local execution policy"] --> J["Leased job + atomic checkpoint"] --> G W["Authenticated channel event"] --> K["Exact route + durable lease"] --> G X["Optional provider-neutral adapter"] --> S["Optional Ed25519 origin check"] --> Q["Local import quarantine"] --> F G --> E["Claude Code · Codex · MCP"] ``` The resolver keeps three concerns separate: | Layer | Purpose | Typical sources | Can grant rights? | |---|---|---|---| | Constitution | Fixed instructions and dated directives | `CLAUDE.md`, `AGENTS.md`, `RULES.md` | Only the real host policy can | | Soul | Stable voice, identity, goals, character | `SOUL.md`, existing persona files | No | | Memory | Small linked facts and an index | `MEMORY.md`, `memory/**/*.md` | Never | Other Markdown remains discoverable as reference material. Names and folders provide initial hints only: the agent itself can classify documents and connect them in a reversible overlay graph. A document becomes protected when it is a native instruction, soul, memory source, or is explicitly linked from one. ## Quick start Requires Node.js 20.9 or newer. ```bash git clone https://github.com/Maykbiletti/AgentSpine.git cd AgentSpine npm install npm test npm link ``` Then point AgentSpine at any existing project: ```bash agentspine scan /path/to/project agentspine context /path/to/project --host codex agentspine briefing /path/to/project --host codex --max-bytes 16384 agentspine verify /path/to/project agentspine audit /path/to/project ``` The generated catalog is written to the operating system's user state directory, never into the scanned project. Set `AGENTSPINE_STATE_DIR` if you want a custom location. ## Install for Claude Code Add this repository as a marketplace and install the plugin: ```text /plugin marketplace add Maykbiletti/AgentSpine /plugin install agent-spine@agent-spine ``` For local development: ```bash claude --plugin-dir . ``` Claude Code discovers the bundled skill, hooks, and MCP server. Review and trust executable components when the host asks. Version `0.73.0` keeps the managed common Codex skill, stable reader verification, assignment continuation and structured completion from `0.72.2`–`0.72.7`, and adds bounded long-session evidence recall without duplicating a host transcript. Claude, Codex, and King use separate deny-by-default source/format adapters; matching tool names never substitute for native provider evidence. A verified `UserPromptSubmit` creates an opaque receipt; only a local owner can consume it with `timeline-enroll --receipt … --confirm-local-timeline` for one immutable private snapshot. Groups stay excluded. After compaction, an agent asks only for one exact UTC time or at least two concrete terms through `session_timeline_search`; `includePriorSessions` can select an already indexed immutable snapshot from the exact same private task after restart. Provider mixing stays off unless the local host sets `AGENTSPINE_TIMELINE_CROSS_PROVIDER=1` and the bounded call also sets `includePriorProviders: true`; every selected snapshot is revalidated with its own provider enrollment and returned with provider provenance. The sidecar is ranked before at most one source is opened, and every returned card carries stable session/message references. A matching real `PreToolUse` provides the one-use binding, so raw MCP, reuse, changed scope, or a changed source returns no history. `session_timeline_capture` can then reverify one exact returned objective result and mechanically place only its measured fields in the existing thread-bound world model. It can also apply a native user message beginning exactly with `Correction: next step:` or `Korrektur: nächster Schritt:` to an existing same-thread continuation; ordinary chat, model text and caller interpretations are ignored. Redacted results and captured knowledge remain context-only and grant no authority. See [bounded session timeline](docs/session-timeline.md). The current structured world view also supports a bounded normal-task continuation checkpoint. It restores the exact confirmed objective, last verified step, open questions and next step after restart or compaction, with source references and without loading transcript history. In an authenticated portal task, the checkpoint and task-subject corrections additionally stay on the exact opaque portal/thread route; another thread with the same task ID cannot read or supersede them. Proposed, conflicting, foreign and completed work is never presented as resumable. See [provenance-bound world model](docs/world-model.md). Version `0.72.0` keeps the durable provenance-bound world model and decomposes the complete outcome-bound learning runtime into bounded contract domains. The current unreleased world view additionally separates facts, user preferences, decisions with rationale, task state, and error lessons. Every typed entry retains evidence, time, scope and optional session/message references; model suggestions remain assumptions, conflicts withhold facts, and explicit corrections preserve superseded history without bloating briefing. Version `0.69.0` splits the CLI into seven bounded domains while preserving all 114 commands and behavior. Version `0.68.0` decomposes the gateway runtime and its regression suite along explicit contract, planning, state, control, run-lifecycle, delivery, inspection and behavioral-test boundaries. The stable `gateway-runtime.js` entrypoint retains the exact public export surface, while every resulting gateway production and test file is governed by the ordinary 500-line budget. Persisted schemas, security gates, atomic state-pair recovery, goal planning, team handoff, resource serialization, tool strategy selection, reflection, exploration and outcome-bound learning remain behaviorally unchanged. Version `0.67.0` makes real AgentSpine use part of every writing delivery contract. Before the first mutation, the hook now requires three ordered, auditable MCP calls bound to the exact session and active goal step: `session_briefing`, `delivery_knowledge_query` for affected targets, contracts and recent errors, then `record_delivery_premortem`. Text claims, foreign-session or foreign-step evidence, and consumed receipts do not count. Missing stages are named precisely at the first write and at completion, while read-only work and verified parser or filesystem uncertainty retain their fail-open behavior. The new knowledge query returns bounded target fingerprints and contract matches as untrusted, context-only evidence; none of these calls grants permissions, tools, delegation or external effects. Version `0.66.1` requires a session- and goal-step-bound premortem before the first direct mutation or any of the recognized common shell-mediated mutations. Exactly three failure checks cover the baseline, contract/tests and delivery path; `Stop` accepts a written delivery only when all three results are closed against both the original premortem digest and the latest observed mutation digest. A later mutation invalidates an earlier closure. Read-only work remains free, technical state uncertainty is audited and fail-open, and closed checks are attached to goal checkpoints and outcome receipts without granting permissions. Large project trees no longer disable the hook when optional Markdown discovery reaches its file, entry or time budget: AgentSpine keeps required sources, skips the remainder deterministically and reports an incomplete-context warning. Version `0.65.0` makes the JavaScript undeclared-call guard differential: existing findings remain visible as exact non-blocking warnings, while only names introduced by the current write block. The comparison uses explicit original edit content, an exact PreToolUse snapshot or the last local audited state; a new file starts from an empty set, and scanner uncertainty remains fail-open. Version `0.64.0` splits the host hook into bounded lifecycle-context and protection modules while preserving the installed hook entrypoint, public exports, event ordering, fail-open scan behavior and fail-closed safety gates. The former 865-line entrypoint is now below the ordinary 500-line budget, and the legacy budget exception has been removed. The same release verifies stated snapshot baselines before direct writes, reports undeclared JavaScript calls after writes, and validates explicitly claimed exchange artifacts after the existing post-write test gate. Unreadable or unparseable evidence is audited without inventing a mismatch. Version `0.63.0` prevents an agent from delivering a changed workspace as finished until a successful supported test command has run after its latest write. The hook records only digest-bound tool evidence outside the repository, carries task-scoped verification across restart, rejects masked or reordered tests, and blocks corrupted evidence cleanly. A waiting self-starter job remains resumable. The same release turns the bounded 16-item self-help ceiling into an explicit plan blocker instead of an exception that kills the worker tick. Version `0.62.0` lets bounded self-help escalate a genuinely unresolved primary-source conflict into exactly one durable owner decision. The runner must first bind repository evidence plus two fresh sources from independent public origins, identify their two conflicting SHA-256 digests, and provide 2-8 distinct options. Without that proof it cannot ask; after local resolution, restart restores exactly one continuation. External content and the answer remain context only and cannot grant authority. Version `0.59.0` adds bounded, outcome-driven exploration to durable plan execution. An owner-confirmed step can freeze two to four attempts; after an objectively measured non-blocking failure, AgentSpine tries exactly one remaining sufficient strategy from the same minimum-risk class. The host receives an immutable attempt number, strategy, budget and previous-outcome digest. Missing or reused evidence, a blocking defect, budget exhaustion and any attempt to enter a higher-risk class stop fail closed. Exploration remains context only and cannot grant tools, permissions or policy exceptions. Version `0.58.0` transfers objectively successful execution strategies to new scope-matching plan steps. A transfer needs two independent passing goals with distinct source digests, the same capability and evaluator contract, an unexpired owner-bound transfer key, and no matching regression. It may break cost ties only inside the lowest-risk sufficient strategy class. A single blocking defect withdraws the strategy from future tasks, while foreign groups, stale evidence and fabricated proof lineages receive the ordinary unproven choice. Transfer records contain only stable IDs, timestamps and digests and never grant tools or authority. Version `0.57.0` adds bounded execution-strategy selection and objective post-action reflection to durable plan steps. An owner-confirmed plan precommits required capability classes, two to eight candidate strategies, risk and cost, plus an evaluator, metric, threshold and minimum case count. AgentSpine selects the lowest-risk sufficient strategy deterministically and will not complete the step from a model or runner self-report alone. The exact strategy and a SHA-256-bound objective outcome must pass; a blocking defect overrides a favorable score. These capability labels remain context only and cannot grant host tools or authority. Version `0.56.0` adds deterministic shared-resource conflict resolution to durable team plans. A step may declare bounded resource IDs in its immutable definition; while that step is leased, only conflicting work in the exact project and group waits. The highest current owner-confirmed goal priority wins even if mutable queue state is altered, while unrelated resources and foreign groups continue in parallel. Resource waits are visible only in the affected agent's scoped gateway context, and completion or lease-expiry recovery releases the resource without granting any tool or authority. Version `0.55.0` adds provider-neutral team execution to durable goal plans. Each dependent step can be bound to a different already-authenticated agent in the same tenant and exact project group, so a plan can move from Codex to Claude and back while preserving one immutable dependency graph, checkpoint chain and objective success criteria. Queue creation, claim, host/profile routing and completion all verify the same step assignee. Foreign-group members, identity drift and assignment tampering fail closed; a departed assignee pauses the exact step before host execution. Historical single-agent plans remain compatible, and plan context never grants tools, delegation or policy exceptions. Version `0.54.0` adds durable, evidence-classified knowledge-gap handling to hierarchical goal plans. A host can pause the exact current step with one bounded question and an objective reason; reconciliation does not ask again, and the step resumes only after an exact locally confirmed answer. Owner input and objective observations remain distinct, objective answers require a SHA-256 source digest, and every answer is context-only. Conflicts, state tampering, secrets and authority-shaped answers fail closed. Version `0.53.0` adds durable hierarchical goal plans to the optional gateway worker. An owner can precommit a bounded dependency graph of objective steps; the worker leases only the current ready step, advances after its explicit success result, resumes the exact step after restart, and reconstructs one missing wake after a torn write. Cycles, definition drift and stale-step completion fail closed, while the plan remains context-only and cannot grant tools, rights or delegation. Version `0.52.1` keeps PreToolUse available when a bounded source or self-starter filesystem scan encounters an inaccessible or disappearing path. EPERM, EACCES, and ENOENT entries are skipped and reported without exposing file content; scan failures on Edit, Write, apply_patch, Bash, and exec_command are allowed and recorded in the local diagnostic audit log. Policy violations and protected-source writes remain fail-closed. Version `0.52.0` makes every locally attested user-feedback or objective-test anchor single-use for experiment admission within its exact scope. Evaluation v28 and bounded retry v29 atomically register content-free lineage tombstones and bind them into candidate admission v4. They survive candidate deletion and subject purge, so a fresh candidate or recreated contract cannot reuse the same evidence or independence identity; parallel races yield one contract, manipulation fails closed after restart, and foreign scopes remain independent with zero matching diagnostics. Version `0.51.0` adds precise local withdrawal of a mistaken evidence-source attestation. `learn-evidence-source-attestation-revoke` binds the exact attestation, candidate admission, evaluation, target and scope without retaining its explanation. The affected lesson is withheld immediately; measurements, projections, deliveries, outcomes and renewal are blocked, and the next locked evaluation pass rolls back the dependent lineage while restoring a safe predecessor. Parallel withdrawal is idempotent, manipulation fails closed after restart, and foreign scopes receive zero diagnostics. Version `0.50.0` requires an explicit local attestation of every qualifying user-feedback or objective-test source before a behavior experiment can begin. Evaluation v26 and bounded retry v27 bind content-free source-class attestations to the exact evidence cohort, target, scope and admission time. Self-labeled chat or model claims cannot open a measurement contract without that confirmation; re-signed class manipulation fails closed after restart, parallel registration remains idempotent, and foreign scopes receive zero diagnostics. Version `0.49.0` prevents chat, memory-like interaction history, or documents alone from opening a behavior experiment. Evaluation v24 and bounded retry v25 freeze a content-free source policy requiring at least one fresh independent explicit-user statement or objective-test anchor before any measurement contract exists. Source-policy manipulation fails closed after restart, parallel registration remains idempotent, and foreign scopes receive zero diagnostics. Version `0.48.0` makes the blocking-defect rule immutable and phase-complete. Evaluation v22 and bounded retry v23 freeze a content-free policy requiring any eligible blocking defect to override cohort averages: a Before defect prevents Canary admission, while After and revalidation defects retain automatic rollback. Policy manipulation fails closed after restart, favorable replay cannot replace a defective evaluator slot, and foreign scopes receive zero diagnostics. Version `0.47.0` freezes the exact fresh evidence cohort before a behavior experiment can start. Evaluation v20 and bounded retry v21 exclude stale evidence, reject future observation times and retain only content-free evidence, independence, class and time metadata under a frozen age policy. Cohort manipulation fails closed after restart, configuration drift cannot move the window, and foreign scopes receive zero diagnostics. Version `0.46.0` requires a candidate to satisfy its frozen confidence and independent-evidence gates before an evaluation contract or measurement lineage can exist. Evaluation v18 and bounded retry v19 embed a content-free candidate-admission receipt bound to the exact target and scope; parallel registration is idempotent, rewritten counts fail closed after restart, and foreign scopes receive zero diagnostics. Version `0.45.0` freezes minimum confidence and independent-evidence requirements in every new behavior evaluation before any benchmark outcome is admitted. Evaluation v16 and bounded retry v17 use those immutable gates despite later configuration changes; scoped status and Context MCP expose only matching content-free counts and digests, while Doctor and audit remain project-wide. Version `0.44.0` makes scoped learning diagnostics fully group-isolated. Every top-level evaluator, binding, lease, retry, exhaustion, staleness and revocation count returned by `learn-status` or the read-only Context MCP is now derived only from candidate records visible to that exact scope; foreign scopes receive zeros without learning whether protected state exists. Unscoped Doctor and audit remain project-wide for local operators. Version `0.43.0` freezes outcome freshness and Canary lifetime in each new evaluation contract. Evaluation v14 and bounded retry v15 carry a digested, content-free staleness policy; later configuration changes affect only future contracts and cannot revive old evidence or extend a registered Canary. Retry comparisons include the policy digest, while scoped status, Doctor and audit expose only counts and digests. Version `0.42.0` protects learning mutations with an owner-bound renewable file lease. A live process keeps its lock beyond the stale threshold, a crashed owner can be recovered, and a process that loses ownership aborts before replacing learning state or deleting the successor's lock. Version `0.41.0` makes the fixed corrective-trial budget independently auditable. A failed attempt 2-of-2 atomically creates one content-free terminal receipt bound to the root evaluation, exact corrective contract, failure, target and scope. Timeout revocation cannot erase the exhausted budget, and foreign groups receive neither the receipt nor its count. Version `0.40.0` makes large image reads quiet: an oversized optional PostToolUse payload is drained and skipped with exit 0, no output and no partial state. Mandatory prompt, source-protection, compaction and completion hooks keep the strict 64 KiB fail-closed boundary. Version `0.39.0` makes corrective trials finite: `agentspine.learning-evaluation/v13` binds the only retry as attempt 2 of 2 to its exact root evaluation and objective comparison contract. A failed corrective Canary cannot be retried again, even when its timeout is locally revoked. Version `0.38.0` keeps a confirmed retry objectively comparable: `agentspine.learning-evaluation/v12` binds its metric, benchmark, case floor, evaluator roots, pairing rules and promotion thresholds to the failed predecessor. A corrected completion timeout is allowed, while moving the measurement goalposts fails closed. Version `0.37.0` makes the retry requirement enforceable. A repeated failed behavior and exact scope can receive `agentspine.learning-evaluation/v11` only after explicit local confirmation binds the latest timeout revocation to a distinct candidate, newly observed evidence and a new contract; the old Canary remains terminal and the safe predecessor stays active. Version `0.36.0` adds locally confirmed withdrawal of one exact invalid initial-trial timeout receipt. The false proof is marked content-free without deleting it, the rolled-back Canary stays terminal, the safe predecessor remains active, and any retry requires a fresh candidate and evaluation contract. Version `0.35.0` adds locally confirmed withdrawal of one exact validation decision, including any dependent renewed lease chain. The lesson is withheld before the next matching context pass and rolled back atomically while its evaluation, measurements, outcomes and user-owned sources remain unchanged. Version `0.34.0` retains the `agentspine.preflight/v2` pre-answer contract, self-healing authenticated persona-to-graph reconciliation, and provider-neutral outcome-bound behavior loop. Every automatic behavior experiment starts with an immutable, locally confirmed evaluation contract and registered evaluator roots. Its content-free target digest freezes the exact evidence-backed candidate revision that the experiment is allowed to prove; later evidence or guidance cannot inherit an earlier result. Locally confirmed evaluation, evidence, measurement, application, delivery and outcome revocation receipts can withdraw one exact invalid contract or proof without storing the explanation in plaintext: any dependent lesson is withheld from the next matching context pass and rolled back atomically, while foreign groups receive neither content nor diagnostics. A revoked contract cannot accept measurements, projections, deliveries, outcomes, promotion or validation renewal; already recorded evidence remains immutable. The initial Before/After cohort precommits each evaluator, principal root, provider run ID, benchmark digest and exact case count before any result or Canary projection exists. A content-free completion policy also freezes the delivery and outcome deadlines before the trial starts. The first exact-scope projections carry the target and policy digests and are admitted atomically; a missing or revoked `Stop`, crash, unmeasured outcome or failed trial creates a blocking condition, removes the Canary from context and rolls it back instead of accepting a later favorable result. Validation remains current only while its content-free evidence lease, exact target, scope, benchmark, evaluator binding and expiry are intact, and renewal keeps the same trial-bound guarantees. Measurement sources and evaluator/run pairs are globally single-use, aliases cannot manufacture independent votes, and no average can hide a blocking defect. All learning remains context-only and cannot create identity, permissions, delegation, credentials, tools, production access, payments or policy exceptions. The installed hook keeps bounded home scanning, excludes configured AgentSpine state only at the exact user home, preserves host-native rules byte-for-byte, and never delegates preflight to model-side MCP. See [safe learning](docs/learning.md), [pre-answer recall gate](docs/preflight-recall.md), and [durable gateway worker](docs/gateway-runtime.md). Verify the installed registration from a checkout with: ```bash npm run host:check npm run host:install-check claude plugin list claude mcp list ``` If AgentSpine is installed but absent from `/mcp`, refresh the cached marketplace copy, reinstall the plugin, start a new Claude Code session, and approve the `agent-spine` server in `/mcp`: ```bash claude plugin marketplace update agent-spine claude plugin uninstall agent-spine@agent-spine claude plugin install agent-spine@agent-spine claude mcp list ``` An unapproved server may appear as `Pending approval`; approval remains a user action and AgentSpine never bypasses Claude Code's trust boundary. After that one host trust decision, enable automatic continuity once for a known local identity: ```bash agentspine entity person:me --kind person --name "Me" --privacy shared agentspine continuity-config /path/to/project --enabled true --entity person:me --confirm-local-opt-in ``` From the next prompt onward, installed lifecycle hooks scan and inject the real scoped `session_briefing` at start, resume, prompt submission, and compaction boundaries. The model does not need to choose `scan`, `context`, or `session_briefing`. The opt-in is separate from host trust because learning conversation signals is a user-controlled privacy decision. Source discovery is independent of the installation `cwd`: Claude uses `CLAUDE_CONFIG_DIR` plus the active project and evidenced project-memory binding; Codex uses `CODEX_HOME` plus its native root-to-`cwd` instruction chain. Inspect the result with `agentspine source-status --host claude|codex --cwd /active/project --json`. See [host-native source roots](docs/source-roots.md). ## Install for Codex AgentSpine ships a native `.codex-plugin/plugin.json` that selects the Codex-only lifecycle adapter. Add the repository to a configured marketplace, open the Codex plugin browser with `/plugins`, install AgentSpine, review the current hook definition with `/hooks`, and start a fresh session. A direct npm/package installation can register both the common user skill and the stable MCP reader with one locally confirmed command: ```bash npm link agentspine host-install codex --confirm-local-host-install --json ``` See [host integration](docs/host-integration.md) for exact component paths and trust behavior. ## Preservation contract AgentSpine's first release is intentionally narrow and testable: - source Markdown is opened read-only; - symlinks are not followed during discovery; - generated state is stored outside ordinary projects; an exact user-home root may contain its explicitly scan-excluded AgentSpine state subtree; - every source receives a SHA-256 fingerprint, byte size, path, layer, and provenance; - native host precedence is retained rather than flattened; - broken links and competing candidates are exposed as findings, never auto-resolved; - linked files are resolved transitively without loading unrelated Markdown; - oversized context stays available through exact ranged reads; - agent write tools are blocked from protected sources by lifecycle hooks; - uninstalling AgentSpine leaves every source file untouched. Read the full [preservation contract](docs/preservation-contract.md), including threat boundaries and deliberate non-goals. ## CLI | Command | Outcome | |---|---| | `agentspine scan [root]` | Discover, classify, fingerprint, and save an external catalog | | `agentspine context [root] --host …` | Resolve relevant sources in deterministic order | | `agentspine briefing [root] …` | Assemble one scoped, privacy-filtered, byte-budgeted session packet | | `agentspine read ` | Read an indexed source range with SHA-256 provenance | | `agentspine verify [root]` | Report added, removed, or byte-changed Markdown | | `agentspine link …` | Add an agent-inferred document relationship to the overlay graph | | `agentspine annotate …` | Add a reversible semantic classification with confidence | | `agentspine entity …` | Add or update a person, agent, group, channel, or project | | `agentspine relate …` | Connect two known entities with privacy and confidence | | `agentspine relationships …` | Read one privacy-filtered relationship neighborhood | | `agentspine attention [root]` | Read sparse due cues after privacy, focus, quiet-hour, and repeat filters | | `agentspine attention-add …` | Record an unanswered question, promise, check-in, or meaningful change | | `agentspine attention-touch …` | Record only that an entity interaction occurred | | `agentspine attention-config …` | Configure limits, quiet hours, silence threshold, or disable attention | | `agentspine attention-delete …` | Permanently remove a cue and its retained attention history | | `agentspine attention-events …` | Inspect durable heartbeat, promise, and blocker events plus optional history | | `agentspine attention-event-delete …` | Permanently remove one lifecycle event, its receipts, history, and presentation state | | `agentspine learn-propose …` | Store an evidence-backed candidate outside accepted context | | `agentspine learn-evidence …` | Append evidence while retaining the previous candidate version | | `agentspine learn-review …` | Explicitly accept or reject a candidate | | `agentspine learn-context …` | Read only accepted, privacy-filtered learning | | `agentspine learn-evaluate …` | Run the default-off low-risk automatic policy | | `agentspine learn-evaluator-register …` | Locally confirm one content-free evaluator principal root | | `agentspine learn-evaluator-revoke …` | Revoke a root, block new evidence, and retain its prior record | | `agentspine learn-evaluation …` | Register an immutable fixed-task contract, or explicitly bind one fresh retry after a revoked trial failure | | `agentspine learn-measurement …` | Register one immutable, content-free external measurement run locally | | `agentspine learn-measurement-revoke …` | Locally revoke one exact invalid measurement and trigger fail-closed withholding | | `agentspine learn-application-revoke …` | Locally revoke one exact invalid turn projection and block every dependent proof | | `agentspine learn-evaluation-revoke …` | Locally revoke one exact invalid evaluation contract and block its complete lineage | | `agentspine learn-validation-revoke …` | Locally revoke one exact invalid validation decision through its renewal chain | | `agentspine learn-trial-failure-revoke …` | Locally withdraw one exact false initial-trial timeout without resurrecting its Canary | | `agentspine learn-delivery-revoke …` | Locally revoke one exact invalid model-turn delivery and trigger fail-closed withholding | | `agentspine learn-outcome-revoke …` | Locally revoke one exact invalid measured result while retaining its immutable measurement | | `agentspine learn-outcome …` | Consume one exact measurement receipt into a contract-, application-, and delivery-bound outcome | | `agentspine learn-measurement-purge …` | Locally purge only stale, unconsumed measurement receipts | | `agentspine learn-status …` | Diagnose contradictions, receipt counts, canary health, and staleness | | `agentspine learn-rollback …` | Restore the accepted fact replaced by a learning | | `agentspine learn-config …` | Configure auto-promotion thresholds, initial-trial outcome deadlines, and context limits | | `agentspine learn-delete …` | Permanently remove one candidate and its learning history | | `agentspine continuity-config …` | Enable, disable, scope, and budget automatic continuity after local opt-in | | `agentspine continuity-status …` | Inspect configuration and minimal signal counts without transcript content | | `agentspine continuity-purge …` | Permanently remove one identity's automatic signals and learned context | | `agentspine source-status …` | Inspect host-native user, project, and memory roots without exposing source contents | | `agentspine source-bind …` | Bind existing user-wide continuity after an explicit local confirmation | | `agentspine source-rollback …` | Disable one source binding while retaining its append-only audit history | | `agentspine source-purge …` | Permanently remove one binding while retaining only its non-reversible digest receipt | | `agentspine delegation-check …` | Check explicit actor/action/target coordination policy; default deny | | `agentspine delegation-grant …` | Owner-confirmed local CLI grant for task coordination only | | `agentspine delegation-revoke …` | Revoke future coordination and retain policy history | | `agentspine task-create …` | Create a context-only task, open thread, or handoff | | `agentspine task-update …` | Update status, assignee, or details while retaining the prior version | | `agentspine tasks …` | Read privacy-filtered current coordination context | | `agentspine execution-grant …` | Create one exact local owner-confirmed job grant; never inferred from context | | `agentspine execution-revoke …` | Revoke future start, resume, and effects while retaining policy history | | `agentspine job-register …` | Register a waiting job with its initial content-bound checkpoint | | `agentspine jobs …` | Inspect durable status, retry, blocker, lease, and checkpoint metadata | | `agentspine job-cancel …` | Stop a job through an explicit local owner decision | | `agentspine job-delete …` | Permanently purge an unleased job, history, and receipts | | `agentspine channel-bind …` | Create or replace one exact locally confirmed provider-to-agent route | | `agentspine channel-revoke …` | Revoke a route and cancel its pending or leased events | | `agentspine channel-policy …` | Inspect local channel bindings without exposing secret values | | `agentspine channel-events …` | Inspect the exact-scope durable ingress queue and leases | | `agentspine persona-sync …` | Synchronize an explicitly approved external authenticated roster | | `agentspine personas …` | Inspect active and historical persona identities and provenance | | `agentspine goal-assign …` | Assign one focused goal or an authenticated multi-agent dependency plan | | `agentspine goal-clarify …` | Resolve one exact plan-bound knowledge gap with locally confirmed context | | `agentspine gateway-control …` | Enable, stop, or kill-switch the local worker under explicit owner control | | `agentspine gateway-status …` | Inspect goals, queue, delivery receipts, and independent health gates | | `agentspine share-init …` | Initialize an optional provider-neutral directory adapter outside the project | | `agentspine share-keygen …` | Create or explicitly rotate a local Ed25519 signing identity | | `agentspine share-trust …` | Trust one exported public identity for the current project | | `agentspine share-trust-revoke …` | Revoke a trusted key without turning signatures into authority | | `agentspine share-publish …` | Publish one explicitly selected accepted, non-private learning | | `agentspine share-pull …` | Import immutable events into local quarantine, never active context | | `agentspine share-snapshot-export …` | Export one immutable signed snapshot outside the scanned project | | `agentspine share-https-publish …` | Create a content-addressed HTTPS object and verify it by read-back | | `agentspine share-https-pull …` | Fetch a bounded signed snapshot through hardened HTTPS into quarantine | | `agentspine share-feed-publish …` | Append one immutable snapshot to a signed ETag-protected feed | | `agentspine share-feed-pull …` | Verify feed continuity and import its latest snapshot into quarantine | | `agentspine share-feed-state …` | Inspect local rollback-protection receipts and retained history | | `agentspine share-peer-serve …` | Answer one live signed snapshot challenge over stdin/stdout | | `agentspine share-peer-pull …` | Pull through an owner-selected executable without invoking a shell | | `agentspine share-sqlite-init …` | Bind an external SQLite file to one authenticated adapter | | `agentspine share-sqlite-publish …` | Append a verified snapshot and atomically advance its hash-linked head | | `agentspine share-sqlite-inspect …` | Validate and inspect the complete local database history | | `agentspine share-sqlite-pull …` | Import the latest fully verified database snapshot into quarantine | | `agentspine share-inbox …` | Review pending, accepted, rejected, superseded, or rolled-back imports | | `agentspine share-review …` | Accept or reject one import through a second local decision | | `agentspine share-context …` | Read only locally accepted, privacy-filtered shared memory | | `agentspine share-rollback …` | Roll back shared supersession and restore the prior record | | `agentspine audit [root]` | Run ten deterministic quality and preservation gates | | `agentspine acceptance` | Run the visible synthetic Claude/Codex lifecycle acceptance and print reproducible receipts | | `agentspine doctor` | Check runtime and preservation mode | | `agentspine mcp` | Start the stdio MCP server | Every command supports `--json` where structured output is useful. The optional SQLite commands use Node.js `node:sqlite` and therefore require Node.js 22.13 or newer; core discovery, CLI, MCP, and the other transports retain the package's declared Node.js support. See the [SQLite transport contract](docs/sqlite-transport.md). ## MCP tools ```mermaid flowchart LR S["scan"] --> R["resolve_context"] R --> B["session_briefing"] B --> Q["read_document"] Q --> V["verify"] E["upsert_entity"] --> L["link_entities"] L --> C["relationship_context"] ``` - `scan` builds the source map. - `resolve_context` selects constitution, soul, memory index, and linked facts for the current host and directory. - `session_briefing` combines only the relevant native sources, current tasks, relationships, accepted learning, reviewed shared memory, and optional cues within a hard compact-JSON byte budget. - `read_document` retrieves exact byte ranges that did not fit the context budget. - `verify` proves whether source bytes changed since the last scan. - `link_documents` and `annotate_document` let agents build their own semantic map without editing sources. - `upsert_entity`, `link_entities`, and `relationship_context` maintain a privacy-scoped social and responsibility map outside the project. - `upsert_attention`, `record_activity`, `attention_context`, `resolve_attention`, `configure_attention`, and `delete_attention` provide sparse follow-up suggestions without sending messages or granting authority. - `propose_learning`, `add_learning_evidence`, `review_learning`, `learning_context`, `learning_outcome_status`, `evaluate_learning`, `rollback_learning`, `configure_learning`, and `delete_learning` keep observations separate from accepted context and preserve every relevance change. Outcome writes remain local runtime/CLI operations; MCP receives only their read-only status. - `check_delegation`, `create_task`, `update_task`, and `task_context` coordinate work under a separate default-deny policy. MCP intentionally has no policy grant, revoke, or permanent task-delete tool. - `shared_context` reads only locally reviewed shared memory. MCP intentionally cannot initialize adapters, publish, pull, inspect the pending inbox, review imports, roll back, or delete. - `record_delivery_premortem` records the exact three context-only failure checks for one hook-issued requirement before mutation. Its sealed receipt is bound to the session and active goal step and grants no permissions or tool access. - `record_world_assertion` stores one immutable measured, explicitly user-confirmed, or model-proposed assertion outside source files; optional typed knowledge distinguishes facts, user preferences, decisions, task state, and error lessons. `world_context` returns only unexpired, non-conflicting established facts while exposing assumptions, stale evidence, contradictions, and opt-in correction history separately. An exact resumable task adds at most six matching confirmed entries with source references. - `session_timeline_index`, `session_timeline_search`, and `session_timeline_capture` provide explicitly enrolled, scope-bound bounded indexing, time-or-two-term recall, and explicit structured capture of one reverified objective result or strictly prefixed native user next-step correction. An explicit same-task prior-session query ranks only the signed sidecar before verifying one immutable source and returns stable session/message references. Capture derives provenance and exact portal/thread/task scope from that source and the authenticated host rather than tool claims. The tools never register arbitrary paths, return raw transcript bytes, infer ordinary chat as facts, or add authority. See [bounded session timeline](docs/session-timeline.md). - `audit` runs the same ten gates available through the CLI. Relationship updates supersede the active view but retain the previous observation in append-only graph history. Permission-like and credential-like attributes are rejected recursively. See [relationships and learning](docs/relationships.md). Attention is deliberately restrained: installed hooks retain minimal heartbeats, promises, and blockers without storing transcripts; each event requires an exact known actor/project/task scope; private and group visibility stays exact; and quiet hours, focus, throttling, lifecycle transitions, deletion, and purge remain enforceable. Events are context only—they send no messages, start no work, and grant no authority. See [attention](docs/attention.md). Configurable autonomy is enforced per explicitly registered project and exact tenant/group scope. Four cumulative levels separate bounded observation, proactive advice, reversible local execution and publication. Execute/publish decisions also require a current exact execution grant; publish needs a separate local confirmation. The project portfolio scans only enrolled non-symlinked roots, classifies evidence, deduplicates findings and exposes at most one rate-limited context notice. It never discovers sibling projects or creates authority. See [configurable autonomy](docs/autonomy.md). Safe learning is evidence-first: general candidates remain invisible until reviewed. Low-risk behavior candidates additionally require a locally confirmed immutable evaluation contract and independent fixed-task measurements before and after an exact-scope Canary. After-results count only when they bind to that unchanged contract, distinct preflight-bound projection receipts and exact-session model-stop delivery receipts. The contract freezes completion deadlines before the first trial; missing delivery or outcome evidence becomes a blocking receipt and automatic rollback. Model self-evaluation cannot promote a lesson, later configuration cannot lower frozen thresholds, and no average can hide a blocking defect. A separate default-off continuity opt-in can automatically accept only direct, high-confidence style, preference, no-go, correction, project-fact, and reference signals. Sensitive personal facts, secrets, identity merges, private group content, and operational or authority claims are always rejected. See [automatic continuity](docs/automatic-continuity.md) and [safe learning](docs/learning.md). Delegation is intentionally narrower than authority: a relationship such as `responsible-for` never permits assignment. Cross-entity task actions require an explicit local actor/action/target grant, while tasks, open threads, and handoffs remain context-only. See [delegation and coordination](docs/coordination.md). Shared memory is transport-neutral and double-reviewed: only accepted non-private learning may be published, every import enters quarantine, and the receiving installation must confirm it again before it can appear in context. The reference directory adapter works without a cloud account. Signed adapters can be exported as immutable snapshots, published as create-only content-addressed HTTPS objects, discovered through signed ETag-protected feeds with local rollback receipts, or requested live through a challenge-response stdio peer. HTTPS pulling uses pinned DNS, SSRF protection, strict limits, verified read-back, and optional environment-supplied bearer authentication. Peer pulling delegates the carrier to one explicit owner-selected executable without AgentSpine invoking a shell. Digests and Ed25519 envelopes protect transport integrity and configured origins; neither grants authority or approves content. See [shared memory adapters](docs/shared-memory.md), [HTTPS snapshots](docs/https-transport.md), [immutable HTTPS objects](docs/object-transport.md), [signed mutable feeds](docs/feed-transport.md), and [peer transport](docs/peer-transport.md). Session briefing keeps that growing context usable: one scoped read prioritizes the current request, explicit stops, and current task; deduplicates local and shared facts; defaults to focus mode; enforces exact group audiences; and measures the entire compact JSON result against the requested byte ceiling. Native lifecycle hooks now inject this packet automatically instead of asking the model to call MCP. See [session briefing](docs/session-briefing.md). The authenticated channel-wake runtime prevents an incoming provider message from losing its recipient or origin. A locally confirmed binding fixes provider, tenant, account, chat, thread, sender, agent, project, group, and session; HMAC-authenticated events enter one durable leased lane and the installed host hook injects the exact message with its compact voice brief. The optional `agentspine-worker` now supplies the missing gateway responsibilities: automatic external-roster synchronization, Telegram polling, exact host-run requests, bounded checkpoints, crash recovery, and idempotent delivery back to the origin. It runs only when the owner starts or supervises it and remains outside MCP. See [authenticated channel wake](docs/channel-runtime.md), [durable gateway worker](docs/gateway-runtime.md), and the [OpenClaw/Hermes reference study](docs/harness-reference.md). The rights-bound self-starter is a separate execution path. A genuine local owner action must grant one exact actor, job, task, target, project, host, and finite tool-capability set. Installed hooks then acquire one lease, recheck authority before every effect, checkpoint the workspace after every result, and resume only an unchanged checkpoint. Memory, Markdown, relationships, learning, attention, task text, previous approvals, and MCP can never create that grant. See [rights-bound self-starter](docs/selfstarter.md). ## Optional four-layer starter New agents that do not have identity files yet can start with the included [`spine-example/`](spine-example/) template: | Layer | Holds | Expected change rate | |---|---|---| | Identity | Name, purpose, stable principles | Almost never | | Voice | Tone, language, and expression | Rarely | | Conduct | Working behavior and verification habits | On explicit feedback | | Grown history | Dated experience and corrections | Append-only | The common [`skills/agent-spine/SKILL.md`](skills/agent-spine/SKILL.md) documents the bounded readiness and delivery workflow. It does not grant tools or permissions. AgentSpine never migrates an established agent into the example, and the normal plugin resolver continues to discover and preserve whatever files already exist. ## Design principles 1. **Preserve before learning.** No useful memory feature justifies destroying the history it is meant to protect. 2. **Memory is data, never authority.** A remembered sentence cannot create permissions, bypass review, or widen access. 3. **Relevance changes; history does not disappear.** New information adjusts confidence and relevance instead of silently overwriting old records. 4. **Identity is contextual.** People, agents, groups, and channels receive separate stable identities until an explicit link proves otherwise. 5. **Human warmth cannot outrank the task.** Relationship context stays small and yields first when context is tight. 6. **Local operation is complete.** Remote or shared-memory adapters are optional extensions, not hidden requirements. ## Project status AgentSpine is in active early development. `v0.8` adds authenticated persona synchronization, a compact voice bridge, an optional durable gateway worker, exact Telegram ingress and delivery, focused goals, per-agent lanes, leases, recovery, and independent health gates. Automatic lifecycle behavior requires the host to discover and trust the current hook definition; a staged direct hook invocation is not treated as proof of that real host decision. Every external effect remains current-rights-bound and default-deny, and existing source Markdown remains immutable. ## Documentation | Goal | Start here | |---|---| | Understand the system | [Architecture](docs/architecture.md) | | Audit non-destructive behavior | [Preservation contract](docs/preservation-contract.md) | | Integrate a host | [Claude Code and Codex](docs/host-integration.md) | | Bind an authenticated external message | [Authenticated channel wake](docs/channel-runtime.md) | | Run automatic roster, goal, and Telegram work | [Durable gateway worker](docs/gateway-runtime.md) | | Compare harness design choices | [OpenClaw and Hermes reference study](docs/harness-reference.md) | | Reproduce the complete host behavior | [Visible cross-host acceptance](docs/acceptance.md) | | Enable automatic continuity | [Automatic continuity](docs/automatic-continuity.md) | | Load one compact session packet | [Session briefing](docs/session-briefing.md) | | Persist measured facts and visible uncertainty | [Provenance-bound world model](docs/world-model.md) | | Resume one exactly authorized job | [Rights-bound self-starter](docs/selfstarter.md) | | Understand relationships and history | [Relationships](docs/relationships.md) | | Configure sparse follow-ups | [Attention](docs/attention.md) | | Review evidence-backed observations | [Safe learning](docs/learning.md) | | Coordinate agents without memory-based authority | [Delegation and coordination](docs/coordination.md) | | Exchange reviewed context between installations | [Shared memory adapters](docs/shared-memory.md) | | Publish or pull signed static snapshots | [HTTPS snapshot transport](docs/https-transport.md) | | Publish immutable content-addressed objects | [HTTPS object transport](docs/object-transport.md) | | Discover successive snapshots safely | [Signed mutable feeds](docs/feed-transport.md) | | Pull directly from another installation | [Challenge-response peer transport](docs/peer-transport.md) | | Verify or cut a release | [Release process](docs/releasing.md) | | Run the Definition of Done | [Ten quality gates](docs/quality-gates.md) | | See planned capabilities | [Roadmap](docs/roadmap.md) | | Cut a release | [Release process](docs/releasing.md) | | Contribute safely | [Contributing](CONTRIBUTING.md) | | Report a vulnerability | [Security policy](SECURITY.md) | ## License Apache License 2.0. See [LICENSE](LICENSE).