Micro ECF

Micro ECF is a lightweight local context layer for builders who want safer agents.

It builds local source maps, policy summaries, and citation-ready context packets from bounded repo/docs/database-summary inputs, then exports Agent OS Harness files for no-spend deployment preview.

npx agoragentic-micro-ecf@latest init --dir .
npx agoragentic-micro-ecf@latest index . --output-dir .micro-ecf
npx agoragentic-micro-ecf@latest build-packet --policy .micro-ecf/policy.json --source-map .micro-ecf/source-map.json --output-dir .micro-ecf
npx agoragentic-micro-ecf@latest export --agent-os --policy .micro-ecf/policy.json --output .micro-ecf/harness-export.json

Expected output: ECF.md, .micro-ecf/source-map.json, .micro-ecf/policy-summary.json, .micro-ecf/context-packet.json, and .micro-ecf/harness-export.json.

Proof demo: .env stays blocked while allowed sources keep citations.

Micro ECF is not a semantic RAG engine, vector store, hosted answer pipeline, or Full ECF runtime. It tells an agent what context is allowed, where it came from, what is blocked, and what can be exported into an Agent OS deployment preview.

Micro ECF runs locally and does not require Agoragentic Cloud.

Use agoragentic-micro-ecf when you want lightweight local policy/source artifacts before hosted deployment. Use agoragentic-ecf-core when you need richer self-hosted context governance.

Agoragentic family

Repo / package	What it is
agoragentic-micro-ecf (this repo)	Open local context wedge (npm agoragentic-micro-ecf)
agoragentic-ecf-core	Self-hosted context-governance runtime (npm agoragentic-ecf-core)
agoragentic-integrations	50+ agent-framework adapters + SDK & MCP server (npm agoragentic-mcp)
agoragentic-premortem-golden-loop	Pre-launch release-readiness CLI (npm agoragentic-premortem-golden-loop)
agoragentic-summarizer-agent	Python example: route summarize via execute()
agoragentic-openai-agents-example	OpenAI Agents SDK marketplace example

Home: agoragentic.com · all packages: npm view <name>

What This Means For Builders

When a builder installs Micro ECF on a codebase, the repo gains a persistent AI work boundary. Future agents can read the generated AGENTS.md, ECF.md, .micro-ecf/context-packet.json, .micro-ecf/policy-summary.json, and .micro-ecf/source-map.json before making changes.

That gives the builder:

• continuity across Codex, Cursor, Claude, Gemini, and other IDE-agent sessions
• an explicit list of allowed and blocked local sources
• citation-ready context packets for reviewing why an agent used a source
• local tool, budget, approval, memory, and swarm boundaries
• resident worklog, docs-sync plan, and handoff artifacts for long goals
• an Agent OS Harness export when the builder wants a no-spend hosted preview

Micro ECF does not replace source-code inspection. It gives agents a durable starting contract and local governance packet so they know what to inspect, what not to expose, and what should require owner review.

The resident memory layer adds continuity for work that spans multiple chats or IDE restarts. It records the active goal, checkpoints, commits, validation, unfinished work, docs-impact plan, and next prompt in local .micro-ecf/ files that a future agent can inspect. This is not cloud memory or hidden agent state; it is a local file ledger the builder can review, edit, or delete.

Agent OS Upgrade Path

Use this guide when you want the shortest path from local Micro ECF artifacts to hosted Agent OS readiness:

• Micro ECF To Agent OS Guide
• When to upgrade from Micro ECF to ECF Core
• Roadmap overview image

Product Boundary

Micro ECF is not Full ECF.

Use this product rule everywhere:

Micro ECF is the local context wedge.
ECF Core is the open-source self-hosted context-governance runtime.
Agent OS is the deployment product.
Full ECF is private/internal infrastructure.

Architecture rule:

Micro ECF may prepare context for Agent OS, but it must not contain the private runtime,
settlement, trust-ranking, or enterprise governance internals that make Agoragentic defensible.

Learning memory follows the same boundary. It may rank, block, route, summarize, or recommend review guidance, but it must never auto-approve, auto-dispatch, spend funds, mutate code, deploy, change secrets, publish marketplace listings, or bypass human/ECF approval.

What Micro ECF Does

Micro ECF helps a builder answer:

Given the context my tools already have or can locally summarize, what is this agent
allowed to know, cite, use, act on, and export into an Agent OS deployment preview?

Core capabilities:

• bounded local source inventory and summarization
• context packet generation from source summaries/provenance
• citation/source maps for allowed local artifacts
• policy summaries
• tool/context allowlists
• small workflow maps
• optional context-provider declarations for RAG/code-graph/MCP systems
• pre/post-action governance inputs for the Consequences Engine
• review-only learning-memory boundary metadata
• deployment-intent files
• Agent OS Harness export
• optional local MCP server

Good inputs:

• markdown/docs
• small repos
• local files
• SQLite files and schema/data summaries
• small Postgres/MySQL exports
• API docs
• agent configs
• test harnesses
• local policy files

Generated outputs:

ECF.md
.micro-ecf/context-packet.json
.micro-ecf/policy-summary.json
.micro-ecf/source-map.json
.micro-ecf/harness-export.json
.micro-ecf/deployment-preview.json
.micro-ecf/resident-status.json
.micro-ecf/context-pack.json
.micro-ecf/worklog/current.json
.micro-ecf/worklog/history.jsonl
.micro-ecf/worklog/checkpoints.jsonl
.micro-ecf/worklog/latest-summary.md
.micro-ecf/docs-sync-plan.json
.micro-ecf/handoff.json
.micro-ecf/handoff.md
.micro-ecf/next-session.md
AGENTS.md
MICRO_ECF_LLM_BOOTSTRAP.md

What A Context Packet Is

A Micro ECF context packet is a governance artifact, not a retrieved-answer bundle.

It contains:

• source IDs, paths, hashes, summaries, citation IDs, and provenance
• allowed and blocked context classes
• export boundaries such as raw_content_exported=false
• references that Agent OS or an IDE assistant can use to inspect the real source files

It does not contain:

• embeddings
• vector indexes
• semantic search results
• model-generated answers
• raw secret or private-file contents
• Full ECF private context graph internals

Use direct source reads, your own RAG, GitNexus, or another MCP/context provider as the source of truth for deep retrieval. Use Micro ECF to govern what those systems may expose or act on.

ECF.md

ECF.md is the persistent agent-readable Micro ECF contract for a local project. It follows the same practical pattern as other agent-readable project contracts: machine-readable front matter plus human-readable rationale.

Use it when a new Codex, Cursor, Claude, Gemini, database, or IDE agent conversation needs to know:

• what Micro ECF is doing in this repo
• which sources are allowed
• which sources are blocked
• how to verify Micro ECF is installed
• when to use .micro-ecf/* artifacts
• when to export an Agent OS Harness packet

Commands:

micro-ecf lint ECF.md
micro-ecf diff ECF.md ECF-next.md
micro-ecf spec

What Micro ECF Does Not Include

Do not add these to Micro ECF:

• semantic/vector retrieval engine
• hosted RAG answer path
• embedding store or model-backed reranker
• Full ECF private context graph internals
• tenant isolation runtime
• enterprise connector architecture
• enterprise audit-log internals
• marketplace ranking, trust, or fraud internals
• router provider-selection internals
• wallet settlement internals
• x402 settlement executor internals
• hosted provisioning code
• private connectors
• secrets broker
• operator prompts
• customer-control evidence tooling
• internal policy scoring for enterprise approvals

Micro ECF can produce inputs and governance envelopes for those systems. It should not implement them.

One-Command Setup

If you are using an IDE LLM, paste this GitHub folder link into the chat:

https://github.com/rhein1/agoragentic-micro-ecf

Then ask it to follow LLM_INSTALL.md. The required flow is:

micro-ecf plan --dir .
# show the plan and wait for explicit approval
micro-ecf install --dir . --yes

plan is read-only. install without --yes refuses to write files and returns the approval plan.

Important: installing Micro ECF creates persistent repo artifacts. It does not automatically inject hidden context into every future LLM conversation.

For future conversations, use one of three handoff paths:

• Compatible IDE agents should auto-read AGENTS.md, then inspect .micro-ecf/policy-summary.json, .micro-ecf/context-packet.json, and .micro-ecf/source-map.json.
• Any other LLM chat should receive MICRO_ECF_LLM_BOOTSTRAP.md as a pasted or attached bootstrap file at the start of the conversation.
• IDEs that support persistent MCP tools can run micro-ecf serve-mcp --root .micro-ecf and configure that server once.

For the full after-install checklist, see POST_INSTALL.md.

From this repo:

npm test
node bin/micro-ecf.mjs plan --dir ../my-agent
node bin/micro-ecf.mjs install --dir ../my-agent --yes

From npm:

npx agoragentic-micro-ecf@latest explain
npx agoragentic-micro-ecf@latest plan --dir .
npx agoragentic-micro-ecf@latest install --dir . --yes

The binary is intentionally simple:

micro-ecf init
micro-ecf scan
micro-ecf doctor
micro-ecf lint ECF.md
micro-ecf plan
micro-ecf install --yes
micro-ecf index ./docs
micro-ecf build-packet
micro-ecf export --agent-os
micro-ecf search --query "..."
micro-ecf validate-policy
micro-ecf serve-mcp
micro-ecf status --write
micro-ecf context-pack --write
micro-ecf resident status
micro-ecf resident refresh
micro-ecf mcp-config --target codex --write
micro-ecf worklog begin --goal "..."
micro-ecf worklog checkpoint --summary "..."
micro-ecf worklog finish --summary "..."
micro-ecf docs-sync plan
micro-ecf handoff --write

Resident Work Memory

Use the resident worklog when a goal spans multiple IDE or Codex conversations:

micro-ecf worklog begin --goal "Implement local proof runner"
micro-ecf worklog checkpoint --summary "CLI and receipt verifier are drafted" --validation "npm test"
micro-ecf worklog finish --summary "Committed local proof runner" --commit abc123 --tests "npm test" --next-prompt "Harden receipt verification"
micro-ecf docs-sync plan --dir .
micro-ecf handoff --write

The worklog and handoff artifacts are local-only. docs-sync plan proposes documentation updates but does not edit docs. Micro ECF will not auto-edit documentation unless a future explicit apply command is added and intentionally run.

For builders, the resident files answer five practical questions at the start of the next session:

• What goal was active?
• What changed and which files were involved?
• Which validation ran?
• Which docs probably need updates?
• What exact next prompt should the next agent continue from?

For a single local refresh before closing an IDE or Codex session, use:

micro-ecf resident refresh --dir .

resident refresh writes only .micro-ecf/ resident artifacts: resident-status.json, context-pack.json, docs-sync-plan.json, handoff.md, handoff.json, and next-session.md. It does not deploy, spend, mutate wallets, settle x402, publish marketplace listings, provision hosted runtime, or expose Full ECF private internals.

If Codex or another IDE supports local MCP tools, micro-ecf serve-mcp --root .micro-ecf exposes read-only resident tools for future sessions:

• micro_ecf.worklog_status
• micro_ecf.handoff
• micro_ecf.work_memory

Local Workflow

Initialize a local project:

npx agoragentic-micro-ecf@latest init --dir ./my-agent

Verify the local install and inspect the context boundary without writing:

npx agoragentic-micro-ecf@latest doctor --dir ./my-agent
npx agoragentic-micro-ecf@latest scan --dir ./my-agent

Index bounded local context:

npx agoragentic-micro-ecf@latest index ./my-agent/docs --output-dir ./my-agent/.micro-ecf

Build local artifacts:

npx agoragentic-micro-ecf@latest build-packet \
  --policy ./my-agent/.micro-ecf/policy.json \
  --source-map ./my-agent/.micro-ecf/source-map.json \
  --output-dir ./my-agent/.micro-ecf

Export an Agent OS Harness packet:

npx agoragentic-micro-ecf@latest export --agent-os \
  --policy ./my-agent/.micro-ecf/policy.json \
  --output ./my-agent/.micro-ecf/harness-export.json

Then hand it to hosted Agent OS:

AGORAGENTIC_API_KEY=amk_your_key npx agoragentic-os@latest deploy readiness --file ./my-agent/.micro-ecf/harness-export.json
AGORAGENTIC_API_KEY=amk_your_key npx agoragentic-os@latest deploy preview --file ./my-agent/.micro-ecf/harness-export.json
AGORAGENTIC_API_KEY=amk_your_key npx agoragentic-os@latest deploy create --file ./my-agent/.micro-ecf/harness-export.json

The export itself is no-spend and non-provisioning. readiness and preview are no-spend checks. deploy create records a hosted deployment request; funding, runtime provisioning, public API exposure, marketplace selling, and x402 monetization remain separate approval-gated steps.

Legacy Export Helper

The original helper remains available:

node export-agent-os-harness.mjs \
  --policy policy.example.json \
  --output ./agent-os-harness.packet.json

Use the CLI for full local context artifacts. Use the helper when you only need a Harness packet from a policy file.

Local MCP Server

Micro ECF can run as a local stdio MCP server:

micro-ecf serve-mcp --root .micro-ecf

Tools:

• micro_ecf.search_context
• micro_ecf.get_source
• micro_ecf.get_policy
• micro_ecf.build_packet
• micro_ecf.export_agent_os_harness

The MCP server reads and writes local .micro-ecf artifacts only. It does not call Agoragentic Cloud.

Context Providers

Micro ECF can attach optional context providers for pre-action impact review. A provider brings its own retrieval, graph, or database engine; Micro ECF records the provider contract, policy boundary, and evidence shape so Agent OS can evaluate blast radius before an agent acts.

Full guide: PROVIDER_WRAPPING.md.

Framework guide: FRAMEWORKS.md.

Evidence/eval backlog: AGENT_OS_EVIDENCE_EVAL_BACKLOG.md.

Supported provider types:

Type	Description
code_graph	Codebase structural awareness: functions, imports, call chains, dependencies
retrieval_context	RAG, document retrieval, database schema/context, or other context engines that return cited evidence
tool_graph	Tool and API dependency graph
policy_graph	Governance and compliance policy relationships
workflow_graph	Multi-step workflow and process dependencies
receipt_graph	Transaction and receipt chain relationships
marketplace_graph	Marketplace listing and seller dependency graph
enterprise_context_graph	Reserved for Full ECF / enterprise deployments, not local Micro ECF internals

Existing RAG As retrieval_context

If you already have RAG, keep it. Configure it as a provider:

{
  "context_providers": [
    {
      "provider_id": "ctx_local_rag_docs",
      "type": "retrieval_context",
      "provider": "local_rag",
      "mode": "local_mcp",
      "enabled": true,
      "scope": "docs_and_repo",
      "capabilities": ["query", "retrieve", "cite"],
      "required": false,
      "required_for_action_classes": ["read_only", "code_change"],
      "mcp": {
        "server": "local-rag",
        "transport": "stdio"
      }
    }
  ]
}

Your RAG provider owns retrieval. Micro ECF owns the policy envelope: allowed sources, blocked sources, citation requirements, budget/action gates, and whether an action should fail closed if the provider is unavailable.

GitNexus As Optional code_graph

GitNexus can be used as an optional local code_graph provider. Treat it as a provider pattern, not a dependency or rebrand.

{
  "context_providers": [
    {
      "provider_id": "ctx_gitnexus_local",
      "type": "code_graph",
      "provider": "gitnexus",
      "name": "GitNexus",
      "mode": "local_mcp",
      "status": "available",
      "enabled": true,
      "scope": "workspace",
      "capabilities": ["impact", "context", "query", "detect_changes", "generate_map"],
      "required": false,
      "required_for_action_classes": ["code_change"],
      "mcp": {
        "server": "gitnexus",
        "transport": "stdio"
      }
    }
  ]
}

If no provider is configured or reachable, Agent OS falls back to standard policy/consequence review. Micro ECF does not silently replace the provider with a hidden RAG system.

How It Connects To Agent OS

Funnel:

1. Builder installs Micro ECF locally.
2. Builder points it at repo/docs/db.
3. Micro ECF builds source maps, policy summaries, and context packets from allowed local summaries/provenance.
4. Builder sees what the agent can safely know, cite, use, and which external context providers may be consulted.
5. Micro ECF exports Agent OS Harness files.
6. Builder previews deployment on Agoragentic.
7. If they want runtime, wallets, APIs, receipts, marketplace, or x402 monetization, they move to Agent OS.
8. If they outgrow static local artifacts but still do not need hosted deployment, they move to ECF Core.
9. Full ECF remains private/internal infrastructure and is not included in Micro ECF or ECF Core.

Canonical hosted contracts:

• https://agoragentic.com/agent-os-harness.json
• https://agoragentic.com/schema/agent-os-harness.v1.json
• https://agoragentic.com/schema/micro-ecf-policy.v1.json
• https://agoragentic.com/agent-os/launch/
• https://agoragentic.com/agent-os/deployments/

Schemas

Local schemas:

• schema/micro-ecf-policy.v1.json
• schema/agent-os-harness.v1.json
• schema/context-packet.schema.json
• schema/source-map.schema.json
• schema/policy-summary.schema.json
• schema/deployment-preview.schema.json
• schema/harness-export.schema.json

Publishing

Micro ECF should be published through npm Trusted Publishing. Do not add long-lived npm write tokens to GitHub Actions.

See TRUSTED_PUBLISHING.md.

License

Micro ECF is licensed under Apache-2.0. The wider integrations repository may contain other adapters under the repository-level license; this folder carries its own package license boundary.