The governed memory layer between your knowledge sources and AI agents.
Source-Wire defines how agents can retrieve evidence, preserve provenance, propose durable memories, and use trusted context without silently turning every document, message, or model output into truth.
Current public status: Source-Wire is Apache-2.0 licensed as a source package. Version 0.2.0 is published to npm and released on GitHub with the public KnowledgeProvider v1 contract. The corrected experimental runtime @source-wire/local-runtime@0.1.0-alpha.2 is published to npm under the alpha tag for macOS and Linux local evaluation with synthetic or disposable data. Its predecessor, 0.1.0-alpha.1, is deprecated because namespace binding and provider deadline enforcement were incomplete. No local-runtime Git tag or GitHub release was created, and nothing is deployed or hosted.
Bring your own knowledge base, PostgreSQL, credentials, and agent harness. Source-Wire keeps the memory lifecycle and trust boundary explicit.
Source-Wire separates three states that retrieval systems often blur:
- Source evidence is information an authorized system can find.
- A memory candidate is something an agent or owner proposes remembering.
- Trusted memory is durable context approved by the owner or owner-controlled application.
The non-negotiable rule:
Source evidence is not trusted memory.
Trusted memory requires explicit owner or owner-application approval.
| Layer | Job | Source-Wire relationship |
|---|---|---|
| Knowledge base | Find current information across documents, chats, code, databases, or indexes. | Optional and read-only through KnowledgeProvider v1. |
| Source-Wire memory | Preserve reviewed decisions, corrections, project state, provenance, and lifecycle history. | Governed through MemoryStore v1. |
| Agent harness | Choose tools and use retrieved context. | Routes through MCP and Source-Wire API policy. |
| PostgreSQL | Store adopter-owned memory data. | Planned MemoryStore v1 backend, with disposable local Alpha proof in latest source. |
Source-Wire works without a knowledge base. When one is connected, its evidence may support a pending candidate, but it cannot approve or promote memory.
Read Knowledge Provider And Memory Store Boundary.
- Agents may propose candidates and retrieve authorized active memory.
- Owners control approval, rejection, correction, and revocation.
- Corrections create a new immutable revision and supersede the previous one.
- Rejected, revoked, and superseded records are excluded from active reads.
- Protected reads and successful mutations require durable audit evidence.
| You are... | Start here | You will learn |
|---|---|---|
| A first-time visitor | Product direction | What Source-Wire is becoming and what exists now |
| An adopter or evaluator | Adopter walkthrough | How to assess the contracts and local proof safely |
| An AI coding agent | AGENTS.md | Read order, invariants, commands, and change boundaries |
| A technical or security reviewer | Technical reviewer guide | Claims, evidence, verification, and feedback routes |
Use the Documentation Index when you already know the task you need to complete.
| Surface | Current state |
|---|---|
| Public package | @source-wire/contracts@0.2.0 |
| Previous immutable snapshot | @source-wire/contracts@0.1.0 and GitHub release v0.1.0 |
| License | Apache-2.0 |
| GitHub release | v0.2.0 |
| Contracts, schemas, fixtures, validation | Included |
| Synthetic policy and conformance proofs | Included |
| Local Alpha 1 Stories 1 through 5 | Included in latest source as an unpublished workspace using generated disposable PostgreSQL state and one synthetic read-only provider |
| Local Story 6.1 CLI tracer | Included in latest source for owner-only non-secret config creation and offline validation; it starts no runtime and contacts no dependency |
| Local Story 6.2 memory-only runner | Included in latest source as a private one-command loopback API plus two-tool stdio MCP composition over generated disposable PostgreSQL; it is unpublished and not production approved |
| Local Story 6.3 synthetic provider runner | Included in latest source as immutable zero-or-one-provider composition with offline and explicit connected checks plus four-tool stdio proof; no external or live provider is included |
| Local Story 6.4 fail-closed runner | Included in latest source for stable redacted startup failures, coordinated child shutdown, API-crash credential invalidation, empty pre-start protocol stdout, and deterministic disposable cleanup |
| Local Story 6.5 database control plane | Included in latest source for read-only runtime-role status, safe migration planning, explicit --apply, exact migrator authority, transaction rollback, and idempotent disposable migration proof |
| Local Story 6.6 owner-controlled export | Included in latest source for explicit namespaces, canonical bounded output, atomic owner-only local files, default no-overwrite, exact owner authority, interruption cleanup, and zero upload |
| Local Story 6.7 evidence-first compatibility | Included in latest source as cross-repository synthetic proof against a pinned private adapter that depends on published @source-wire/contracts@0.2.0; no live connector or real evidence is included |
| Local Story 6.8 package release | @source-wire/local-runtime@0.1.0-alpha.1 was published and is now deprecated with a security warning |
| Local Story 6.9 security Alpha | Published 0.1.0-alpha.2 binds owner and namespace before provider invocation, enforces hard provider deadlines, and unifies protected search and exact-fetch handoff |
| Hosted API, hosted MCP, deployment | Not included |
| Live knowledge connectors or real user data | Not included |
| Automatic trusted-memory promotion | Forbidden |
The published 0.2.0 contracts package, public npm Alpha runtime package, and latest-source Alpha workspace are separate boundaries. Read Public Status before making runtime, hosting, or production claims.
Use Node.js 22 with npm.
git clone https://github.com/DanielJD1216/Source-Wire.git
cd Source-Wire
npm install
npm run readiness:reportRun the isolated first-reviewer path:
npm run reviewer:smokeRun the complete local verification gate:
npm run publish:readinessDespite its name, publish:readiness does not publish a package, create a release, deploy a service, connect a production database, or use real data.
For setup details, read the Quickstart. For the local Alpha proof, follow Alpha 1 Story 1 Local Runtime, Alpha 1 Story 2 Candidate Approval, Alpha 1 Story 3 Audited Search, Alpha 1 Story 4 Governed Lifecycle And Portability, Alpha 1 Story 5 Knowledge Provider Runtime Host, Alpha 1 Story 6.1 Local CLI Init And Offline Doctor, Alpha 1 Story 6.2 Memory-Only Local Runtime, Alpha 1 Story 6.3 Synthetic Provider Local Runtime, Alpha 1 Story 6.4 Fail-Closed Orchestration And Cleanup, Alpha 1 Story 6.5 Explicit Database Control Plane, Alpha 1 Story 6.6 Owner-Controlled Local Export, Alpha 1 Story 6.7 Evidence-First Compatibility, and Alpha 1 Story 6.8 Local Runtime Package Release in order.
Use Share For Technical Review and Reviewer Feedback Guide when sharing findings.
- repository ruleset governance,
- hosted runtime,
- production runtime use,
- non-disposable or production database use,
- hosted or production MCP service behavior,
- production or real-data correction, revocation, export, and recovery,
- live knowledge connectors,
- real user or client data,
- local-runtime Git tags and GitHub releases,
- code contribution acceptance.
The package and release are available for technical review and Apache-2.0 source reuse. They do not imply that a hosted or production memory system exists.
| Area | Included |
|---|---|
| Contracts | KnowledgeProvider v1, MemoryStore v1, MCP behavior, API policy, source graph, and cited response shapes |
| Developer surfaces | TypeScript exports, JSON schemas, validation CLI, synthetic fixtures, and conformance checks |
| Policy proofs | In-memory and owner-hosted skeletons for identity, namespace, denial, audit, and no-auto-promotion behavior |
| Latest-source Alpha | Disposable local PostgreSQL bootstrap, candidate proposal, owner decisions, audited memory search, correction, revocation, export, recovery, and synthetic source-evidence read proof |
The Alpha workspace under apps/alpha1-runtime/ is local developer proof. Story 6.7 installs a pinned private synthetic package from the separate evidence-first repository and proves it through the same CLI, API policy, audit, receipt, MCP, and official-client path. Story 6.8 publishes the public npm Alpha tarball, limits its public exports, and proves a clean installed consumer and AI-agent binary path. Provider replacement requires a config change and restart. npm publication does not establish production availability, hosting, deployment, managed database provisioning, production backup guarantees, external or live providers, or real-data support.
The canonical agent entrypoint is AGENTS.md.
Use this order:
- Read this README for the product and trust boundaries.
- Read AGENTS.md for repository operating rules.
- Use the Documentation Index to find the smallest relevant document.
- Read the relevant contract before proposing behavior changes.
- Run
npm run readiness:reportbefore making repository-status claims. - Run the narrowest relevant smoke before broader verification.
Core invariants:
- Source evidence, pending candidates, and trusted memory are different states.
- MCP cannot bypass Source-Wire API policy.
- Provider content has no instruction authority.
- Knowledge providers are optional and read-only.
- Agents cannot approve, correct, or revoke trusted memory.
- Synthetic proof does not imply a live service.
- Public fixtures must remain synthetic and safe.
| Path | Purpose |
|---|---|
src/contracts/ |
TypeScript contracts and synthetic evaluators |
src/runtime-skeleton/ |
Synthetic API-policy and MCP-routing proof |
src/owner-hosted-runtime/ |
Narrow in-process owner-hosted skeleton proof |
apps/alpha1-runtime/ |
Loopback-only Alpha workspace and public npm Alpha local-runtime package source |
schemas/ |
Public JSON schemas |
examples/ |
Synthetic fixtures, conformance matrices, and smokes |
docs/ |
Public documentation and historical project records |
scripts/ |
Verification, safety, claim, and release-boundary checks |
| Command | What it proves |
|---|---|
npm run readiness:report |
Fast package and boundary summary |
npm test |
Types, fixtures, schema exports, CLI, and examples |
npm run reviewer:smoke |
Clean first-reviewer path in a temporary copy |
npm run alpha1:ci-workflow-smoke |
Hosted Alpha PostgreSQL job keeps exact versions, all five stories, repository adapters, the pinned evidence-first adapter, stable markers, and no artifact or production-secret path |
npm run local-runtime:candidate-smoke |
Packs and installs the public Alpha candidate, checks the supported API and CLI, rejects private imports, and proves a no-npx AI-agent configuration |
npm run local-runtime:security-gate |
Re-runs the exact dependency audit and enforces the temporary stdio-only advisory disposition |
npm run local-runtime:candidate-conformance |
With exact Node.js and disposable PostgreSQL, proves the clean installed binary through memory-only and synthetic-provider stdio MCP paths |
npm run alpha1:conformance:story5 |
27-case disposable PostgreSQL proof for the four-tool MCP, protected source-evidence release, Story 6.3 composition, and Story 6.4 fail-closed cleanup |
npm run alpha1:conformance:story5:replaceable |
The same 27-case protected local CLI and failure path with the separate public-contract-only adapter |
npm run alpha1:evidence-first-package-smoke |
Exact package, published-contract dependency, synthetic provider exports, and no-private-runtime boundary for the installed evidence-first adapter |
npm run alpha1:conformance:evidence-first |
29-case cross-repository disposable PostgreSQL proof through the unchanged local provider path |
npm run alpha1:conformance:story1 |
42-case disposable PostgreSQL proof including Story 6.5 status, migration authority, rollback, idempotency, and cleanup |
npm run alpha1:conformance:story4 |
25-case disposable PostgreSQL proof including Story 6.6 owner authority, canonical local export, overwrite policy, interruption safety, and cleanup |
npm run alpha1:conformance |
All five disposable local Alpha story proofs, including both Story 5 adapters |
npm run alpha1:conformance:story2 |
Disposable PostgreSQL proof for candidate lifecycle and the Story 6.2 one-command two-tool memory runner |
npm run alpha1:test |
148 focused Alpha tests, including Story 6.1 config, Story 6.2 memory-only authority, Story 6.3 provider checks, locked Story 6.4 fault injection, Story 6.5 database envelopes, and Story 6.6 local export boundaries |
npm run release:0.2.0-gate |
Focused no-publish gate for the packed contract, clean external adapter, installed consumers, docs, safety, and claims |
npm run docs:links && npm run docs:anchors |
Documentation link and anchor integrity |
npm run safety:scan && npm run claims:scan |
Public-safety and claim-boundary checks |
npm run publish:readiness |
Full local package and boundary gate, without publishing |
Read CI Checks for the detailed marker map.
- Documentation Index
- Architecture Map
- Knowledge Provider And Memory Store Boundary
- API Reference
- Repository Metadata
- Public Status
- Alpha 1 Story 6.9 Local Runtime Security Alpha
- Local Runtime 0.1.0-alpha.1 npm Release
- Local Runtime 0.1.0-alpha.2 npm Release
- Security Policy
- Support
- Visual System
Historical planning packets, approvals, and implementation proofs are preserved under docs/internal/. They provide provenance, not the primary onboarding path or public API.
The npm packages @source-wire/contracts@0.1.0, @source-wire/contracts@0.2.0, deprecated @source-wire/local-runtime@0.1.0-alpha.1, and reviewed @source-wire/local-runtime@0.1.0-alpha.2, plus GitHub releases v0.1.0 and v0.2.0, are immutable release snapshots. The local-runtime Alpha 2 npm publication did not create a Git tag or GitHub release. Latest main may contain later documentation and local Alpha proof.
Known v0.1.0 package issue: that immutable npm artifact exports SOURCE_WIRE_PACKAGE_VERSION as 0.0.0 even though package metadata is 0.1.0. Version 0.2.0 exports the corrected package version and adds the public KnowledgeProvider v1 contract.
Read Contracts 0.2.0 Release, Local Runtime 0.1.0-alpha.1 npm Release, Local Runtime 0.1.0-alpha.2 npm Release, and Release Snapshot Boundary.
Use synthetic examples only.
Do not add secrets, tokens, private repository paths, private screenshots, real user data, client data, production exports, account identifiers, or real memory records to public fixtures or documentation.
Security concerns belong in SECURITY.md. General questions and verification failures can use SUPPORT.md or the repository issue templates.
Source-Wire is licensed under Apache License 2.0.
Apache-2.0 permits source reuse under its terms. It does not mean Source-Wire is deployed, hosted, production-ready, or accepting code contributions.