Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

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

Micro ECF: the open local context wedge. A dependency-free CLI + MCP server that compiles your repo into durable, policy-governed local artifacts (ECF.md, source maps, policy summaries, Agent OS Harness exports) a coding agent reads before it edits. No cloud, no wallet. The smallest ECF tier.
https://github.com/rhein1/agoragentic-micro-ecf

ai-agents claude-code cli codex coding-agent context-engineering context-governance cursor ecf llms-txt local-first mcp micro-ecf

Last synced: 4 days ago
JSON representation

Micro ECF: the open local context wedge. A dependency-free CLI + MCP server that compiles your repo into durable, policy-governed local artifacts (ECF.md, source maps, policy summaries, Agent OS Harness exports) a coding agent reads before it edits. No cloud, no wallet. The smallest ECF tier.

Awesome Lists containing this project

README 

          
# 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.



```bash

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](examples/secret-block-proof.md).



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.





  Micro ECF - local context wedge for safer agents




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.





  Micro ECF architecture diagram showing local inputs, bounded context artifacts, blocked secret paths, and Agent OS preview outputs




## Agoragentic family



| Repo / package | What it is |

|---|---|

| **[agoragentic-micro-ecf](https://github.com/rhein1/agoragentic-micro-ecf) (this repo)** | **Open local context wedge (npm `agoragentic-micro-ecf`)** |

| [agoragentic-ecf-core](https://github.com/rhein1/agoragentic-ecf-core) | Self-hosted context-governance runtime (npm `agoragentic-ecf-core`) |

| [agoragentic-integrations](https://github.com/rhein1/agoragentic-integrations) | 50+ agent-framework adapters + SDK & MCP server (npm `agoragentic-mcp`) |

| [agoragentic-premortem-golden-loop](https://github.com/rhein1/agoragentic-premortem-golden-loop) | Pre-launch release-readiness CLI (npm `agoragentic-premortem-golden-loop`) |

| [agoragentic-summarizer-agent](https://github.com/rhein1/agoragentic-summarizer-agent) | Python example: route `summarize` via `execute()` |

| [agoragentic-openai-agents-example](https://github.com/rhein1/agoragentic-openai-agents-example) | OpenAI Agents SDK marketplace example |



Home: **[agoragentic.com](https://agoragentic.com)** · all packages: `npm view `



## 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](./MICRO_ECF_TO_AGENT_OS.md)

- [When to upgrade from Micro ECF to ECF Core](./ECF_CORE_UPGRADE.md)

- [Roadmap overview image](./assets/roadmap/roadmap-overview.png)



![Micro ECF to Agent OS roadmap](assets/roadmap/roadmap-overview.png)



## Product Boundary



Micro ECF is not Full ECF.



Use this product rule everywhere:



```text

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:



```text

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:



```text

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:



```text

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:



```bash

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:



```text

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

```



Then ask it to follow [`LLM_INSTALL.md`](./LLM_INSTALL.md). The required flow is:



```bash

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`](./POST_INSTALL.md).



From this repo:



```bash

npm test

node bin/micro-ecf.mjs plan --dir ../my-agent

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

```



From npm:



```bash

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:



```bash

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:



```bash

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:



```bash

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:



```bash

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

```



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



```bash

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

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

```



Index bounded local context:



```bash

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

```



Build local artifacts:



```bash

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:



```bash

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:



```bash

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:



```bash

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:



```bash

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`](./PROVIDER_WRAPPING.md).



Framework guide: [`FRAMEWORKS.md`](./FRAMEWORKS.md).



Evidence/eval backlog: [`AGENT_OS_EVIDENCE_EVAL_BACKLOG.md`](./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:



```json

{

  "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.



```json

{

  "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:



```text

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`](./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.