Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(research): add ECC competitive analysis

AkitaOnRails072a032c8233
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a399ad57..fd50337d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -683,7 +683,8 @@ under the distinct `provider="openai-compat"` identity.
- what "Karpathy-faithful" means.
* [`docs/research-agentmemory.md`](research-agentmemory.md),
[`research-basic-memory.md`](research-basic-memory.md),
- [`research-cognee.md`](research-cognee.md) - prior art studied.
+ [`research-cognee.md`](research-cognee.md),
+ [`research-ecc.md`](research-ecc.md) - prior art studied.
* [`docs/auto-improvement-loop.md`](auto-improvement-loop.md) -
Hermes Agent-inspired learning-loop research and safety boundaries.
* [`docs/issues-*.md`](.) - concrete failure modes we've designed to
diff --git a/docs/research-2026-landscape.md b/docs/research-2026-landscape.md
index 415a0d56..80f32022 100644
--- a/docs/research-2026-landscape.md
+++ b/docs/research-2026-landscape.md
@@ -78,6 +78,7 @@ The market has consolidated into recognizable camps:
| Fact extractors | **Mem0**, LangMem, Supermemory | LLM extracts atomic facts per turn; lightweight personalization |
| **File-first wiki memory** | **us**, basic-memory, OKF, Letta's filesystem result, mempalace (nominally) | Markdown source of truth, derived indexes, human-editable |
| Code intelligence | DeusData/codebase-memory-mcp | Index the *codebase* (158 languages, static binary) rather than the *session* - adjacent, not competing: it remembers what the code is, not what you did |
+| Agent-harness OS | **ECC** (~247K stars), plus the skills/agents-pack ecosystem | Install a whole plan→test→implement→review→**remember**→improve loop into the agent; memory is one thin pillar ("optimize the context window, persist everything else"), deliberately kept as *context, not policy* - adjacent, not competing (see `research-ecc.md`) |
**Closest architectural sibling: `doobidoo/mcp-memory-service`** (1.9K
stars, 3.2K commits, active through August 2026). It is what we would be
diff --git a/docs/research-ecc.md b/docs/research-ecc.md
new file mode 100644
index 00000000..999f72f5
--- /dev/null
+++ b/docs/research-ecc.md
@@ -0,0 +1,165 @@
+# ECC — Research Report
+
+*Repo:* <https://github.com/affaan-m/ECC> · MIT · primarily JavaScript/TypeScript
+(with Python, Go, Shell). *Snapshot:* 2026-09-03 — ~247k stars, ~37k forks,
+created 2026-01, pushed daily. One of the most-starred AI-agent repos on
+GitHub, single-maintainer-led with an active contributor community.
+
+> **Category caveat, up front.** ECC is **not** a memory backend like
+> ai-memory. It bills itself as *"the agent harness operating system"* — a
+> plan → test → implement → review → verify → **remember** → improve loop
+> installed once into a coding agent (Claude Code, Codex, OpenCode, Cursor,
+> Gemini, Zed, …) as skills, subagents, rules, hooks, and MCP wiring. Memory
+> is one pillar among Skills, Instincts, Security, and Research-first
+> development — not the product. So this report compares only the overlapping
+> surface (its memory / continuous-learning component) and mines it for
+> insights, rather than treating ECC as a like-for-like competitor.
+
+## 1. Purpose & Scope
+
+ECC's pitch: *"Your agent can write code, but ECC gives it a coordinated
+engineering system and toolbox: it plans before it builds, verifies changes
+with tests, reviews its own work from a fresh context, remembers what
+matters, and turns repeated wins into reusable skills and workflows."* The
+memory value prop is captured in one line — **"Optimize the context window.
+Persist everything else."** — which is exactly ai-memory's own reason to
+exist. Where ai-memory *is* the "persist everything else" layer, ECC ships a
+lightweight version of it inside a much larger workflow framework.
+
+ai-memory is the deeper, dedicated memory system; ECC is the broader agent
+scaffolding with a shallow-but-opinionated memory slice. They are adjacent,
+not substitutes.
+
+## 2. Architecture
+
+- **File-based, no server.** State lives as Markdown under
+ `$ECC_AGENT_DATA_HOME` / `.ecc/memory/` (project), version-controlled team
+ memory, and `~/.ecc/memory/` (user). A SQLite state store backs instinct
+ tracking and session recording; git distributes config.
+- **Hook-driven persistence.** PreToolUse / PostToolUse / Stop hooks
+ (`hooks/hooks.json`, with `ECC_HOOK_PROFILE=minimal|standard|strict`
+ runtime gating) capture session summaries and learned patterns — the same
+ lifecycle-hook capture spine ai-memory uses, but writing local files rather
+ than posting to a server.
+- **Skills / Agents / Rules.** ~286 Markdown "skills" (workflows loaded on
+ demand), ~68 subagents with isolated context + scoped tool permissions, and
+ always-loaded language/framework "rules" packs. This is a governance layer
+ ai-memory does not have and does not aim to.
+
+Contrast: ai-memory is a single-writer SQLite + wiki-git **server** with a
+real retrieval engine (FTS5 + vector + entity + graph, fused by RRF) and an
+OKF-portable on-disk format; ECC is a distributed pile of Markdown + a
+SQLite side-table, retrieved by search over active files.
+
+## 3. Memory Model
+
+- **Format:** `ecc.memory.v1` Markdown documents — portable and inspectable
+ (same instinct as ai-memory's OKF-v0.2 human-readable wiki).
+- **Scopes:** project / team / user. The **team scope is version-controlled
+ and shared through git** — a genuinely different multi-user story than
+ ai-memory's server-mediated workspaces (see §6).
+- **Capture:** semi-manual — `ecc memory save`, `ecc memory handoff`
+ (`--stdin` / `--body-file`) — plus hook-driven session summaries. This is
+ the biggest divergence: ai-memory's capture is **automatic and
+ zero-ceremony** (every prompt/tool/session boundary sanitized and stored by
+ lifecycle hooks with no `save` call), whereas ECC leans on explicit save
+ commands for durable notes and reserves automation for summaries.
+- **Retrieval:** `ecc memory search "query"` over active memories, and
+ `ecc memory doctor` for vault integrity. No evidence of hybrid
+ vector/entity/graph retrieval or temporal (`as_of`) queries — it appears to
+ be text search over a curated file set, which is adequate for a small,
+ human-pruned vault but not for a large auto-captured corpus.
+
+## 4. Consolidation & Continuous Learning ("Instincts")
+
+ECC's "Continuous Learning v2" extracts **instincts with confidence
+scoring** from session patterns — *"instinct-based learning with confidence
+scoring, import/export, evolution"* — and can promote recurring wins into
+generated skills. This maps closely to ai-memory's session-end consolidation
++ auto-improve loop, with two notable differences:
+
+1. **Explicit confidence + evolution.** ECC attaches a confidence score to
+ each learned instinct and supports import/export and "evolution" over
+ time. ai-memory's auto-improve is eval-gated and staged, but confidence is
+ implicit; surfacing a per-page/per-rule confidence would be a cheap,
+ legible upgrade.
+2. **Promotion to skills, not just recall.** ECC turns repeated patterns into
+ *executable* skills/workflows, not only retrievable notes — a stronger
+ "learning produces behavior" story than ai-memory's "learning produces
+ better recall."
+
+## 5. Distinctive Ideas Worth Noting
+
+- **"Memory is unreviewed context, not executable policy. Verify important
+ claims against authoritative sources and promote accepted knowledge into
+ governed project documentation."** This is the sharpest idea in the repo. It
+ draws a hard line between *raw captured memory* (untrusted, for context)
+ and *governed knowledge* (reviewed, promoted into rules the agent obeys).
+- **AgentShield** — a bundled security scanner that audits harness config,
+ hooks, MCP definitions, agent files, permissions, and secrets
+ (`ecc-agentshield scan --path .`). ai-memory has a security-audit *skill*
+ but ships no scanner for the hook/MCP config it writes.
+- **Plan Canvas** — browser review of implementation plans (Mermaid
+ diagrams, approval gates). Orthogonal to memory, but a nice human-in-the-
+ loop surface.
+- **Research-first development** — source-verification baked into the flow
+ before knowledge is trusted.
+
+## 6. Cross-Agent / Multi-User
+
+ECC's **team memory is git-shared Markdown** — every teammate pulls the same
+committed vault. ai-memory instead mediates multi-user/multi-machine through
+a **server** (attributed writes, per-user scoping, live sync across
+machines). ECC's model is simpler and offline-friendly but has git's
+merge/conflict story and no live cross-session handoff; ai-memory's is richer
+(real-time handoff, attribution, one store many machines) at the cost of
+running a server. Different trade-offs for different teams.
+
+## 7. What's Good / What's Missing — Honest Take
+
+**What ECC does better (or at least differently, worth stealing):**
+- The **memory-vs-governed-knowledge distinction** as a first-class
+ principle. ai-memory already gestures at this (the lint pass suggests
+ "this looks like a durable rule — copy it into CLAUDE.md/AGENTS.md"), but
+ ECC makes *promotion* an explicit, designed path. ai-memory could formalize
+ a **promotion flow**: memory page → reviewed → emitted as a governed
+ `AGENTS.md`/rule the agent loads every turn, closing the loop the lint only
+ hints at.
+- **Explicit confidence scores** on learned knowledge (cheap legibility win).
+- **A bundled config scanner** (AgentShield analogue) for the hooks/MCP
+ ai-memory itself installs — the data-layer audit this project just ran by
+ hand could become a shippable `ai-memory audit-config`.
+- **Learning that produces behavior** (instincts → skills), not just recall.
+
+**Where ai-memory is clearly ahead (for the memory problem specifically):**
+- **Automatic, zero-ceremony capture** vs ECC's `ecc memory save`. ai-memory
+ never asks the agent to remember to persist.
+- **A real retrieval engine** — hybrid FTS5 + vector + entity + graph RRF,
+ temporal `as_of`, benchmarked on LongMemEval-S (hit@5 0.62 → 0.82) — vs
+ text search over an active file set.
+- **Scale of corpus.** ai-memory is built to auto-capture and retrieve over
+ thousands of pages and hundreds of thousands of observations; ECC's vault
+ is a smaller, human-curated set.
+- **Server-mediated multi-user, temporal windows, OKF portability, and
+ eval-gated consolidation.**
+
+**Bottom line.** ECC is not a memory competitor — it's an agent-harness OS
+whose memory is deliberately thin ("optimize the context window, persist
+everything else; keep memory as context, not policy"). Its best lesson for
+ai-memory is *governance*: the explicit line between raw memory and promoted,
+reviewed, agent-obeyed knowledge, plus confidence scoring and a config
+scanner. Its capture and retrieval are well behind ai-memory's, by design.
+
+## 8. Concrete Ideas to Consider for ai-memory
+
+1. **A promotion path** memory → governed rule (`AGENTS.md`/`CLAUDE.md`),
+ turning the existing "looks like a durable rule" lint into an actual
+ reviewed-and-emitted governance artifact.
+2. **Surface confidence** on consolidated pages / auto-improve proposals
+ (already eval-gated internally; make it legible in `status`/`memory_query`).
+3. **`ai-memory audit-config`** — a shippable scanner for the hook/MCP config
+ ai-memory writes (AgentShield analogue), built from the data-layer audit
+ work already done.
+4. **Consider a lightweight git-shared "team rules" scope** for offline/small
+ teams that don't want to run the server — complementary to, not a
+ replacement for, the server model.