Skip to content

RESEARCH.md

Latest commit

 

History

History
506 lines (475 loc) · 88.3 KB

RESEARCH.md

File metadata and controls

506 lines (475 loc) · 88.3 KB
Raw

engram — research record

Revision and scope

  • Repository: NickCirv/engram
  • Commit: 9fa2a4b74ca8e66560d74d1255c16c43157d32bd
  • Tree: 493929bca5524ad945d86569b393a83000ef3775
  • Captured: 332 of 332 eligible text files (all eligible text files).
  • Recursive tree truncated: False.
  • Runtime verification: unverified; no repository code, installation or test command was executed.

The captured file inventory is broader than the semantic review. Authoring inspected package metadata, entrypoint/argument handling and implementation paths relevant to the claims below, plus test declarations. This is documentation research, not a line-by-line security audit. Generated/binary artifacts, lockfiles and file types outside the acquisition filter were not inspected.

Claim and evidence

Claim Pinned evidence Status
Runtime requirement and executable mapping package.json verified in manifest; installation unverified
Build a local structural code graph and provide focused context to coding agents. implementation partially verified by static implementation review
Operational limits and side effects implementation and source map in reference partially verified; runtime unverified
Test command definition package.json verified as a declaration only

Findings carried into the rewrite

Graph summaries are retrieval aids, not execution traces or complete semantic understanding. Hook output can change what an agent sees. Token estimates and fixture benchmarks are not invoice savings or proof of task accuracy; measure both quality and cost on your workload.

No runtime checks were executed for this documentation review. A declared test command is available below; its presence is not a passing result.

Documentation inventory and disposition

Existing document Disposition
.github/ISSUE_TEMPLATE/bug_report.md Preserved issue-reporting workflow template; not a product usage guide.
.github/ISSUE_TEMPLATE/feature_request.md Preserved issue-reporting workflow template; not a product usage guide.
CHANGELOG.md Preserved policy, legal/specification or historical release text; no overlay replacement.
CLAUDE.md Preserved executable agent/prompt contract; prose refresh does not authorize changing agent behavior.
CONTEXT.md Preserved executable agent/prompt contract; prose refresh does not authorize changing agent behavior.
CONTRIBUTING.md Preserved policy, legal/specification or historical release text; no overlay replacement.
README.md Rewritten overview; historical copy remains at this pinned URL.
SECURITY.md Preserved policy, legal/specification or historical release text; no overlay replacement.
adapters/continue/README.md Rewritten from pinned source; examples and integrations unexecuted.
bench/README.md Rewritten from pinned source; examples and integrations unexecuted.
bench/results/real-world-2026-04-24.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
demo/README.md Rewritten from pinned source; examples and integrations unexecuted.
docs/COMPARISON.md Rewritten from pinned source; examples and integrations unexecuted.
docs/FRONTIER.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/INTEGRATION.md Rewritten from pinned source; examples and integrations unexecuted.
docs/PLAN.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/STATE.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0001-grep-symbol-intercept.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0002-session-level-bench.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0003-same-session-read-dedup.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0004-grep-richer-find-usages.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0005-bash-grep-interception.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0006-honest-before-after-demo.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0007-grep-never-worse-gate.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0008-subagent-context-broker.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0009-recall-coverage-benchmark.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0010-compaction-session-ledger.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0011-defer-bash-explore-interception.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/0012-session-replay-measurement.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/adr/README.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/demos/README.md Rewritten from pinned source; examples and integrations unexecuted.
docs/demos/hf/AGENTS.md Preserved executable agent/prompt contract; prose refresh does not authorize changing agent behavior.
docs/demos/hf/CLAUDE.md Preserved executable agent/prompt contract; prose refresh does not authorize changing agent behavior.
docs/demos/scene-table.md Deferred coordinated media revision: historical scene copy must change alongside HTML, captions and rendered assets; quantitative claims not revalidated.
docs/design/phaseA-displacement-resolver.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/distribution/SUBMISSIONS.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/integrations/README.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/aider.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/ccs.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/claude-code.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/cline.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/continue.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/cursor-mcp.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/emacs.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/neovim.md Rewritten from pinned source; examples and integrations unexecuted.
docs/integrations/zed.md Rewritten from pinned source; examples and integrations unexecuted.
docs/plugins/README.md Rewritten from pinned source; examples and integrations unexecuted.
docs/release-notes-4.3.0.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/release-notes-4.3.1.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/release-notes-4.3.2.md Preserved historical design, ADR, plan, release or measurement artifact; not asserted as current implementation guidance.
docs/specs/2026-04-13-context-spine-design.md Preserved policy, legal/specification or historical release text; no overlay replacement.
docs/specs/ecp-v0.1.md Preserved policy, legal/specification or historical release text; no overlay replacement.
docs/specs/engram-v2-roadmap.md Preserved policy, legal/specification or historical release text; no overlay replacement.
docs/superpowers/specs/2026-04-24-v3.0-spine-implementation.md Preserved policy, legal/specification or historical release text; no overlay replacement.
extensions/vscode/README.md Rewritten from pinned source; examples and integrations unexecuted.
llms-install.md Rewritten from pinned source; examples and integrations unexecuted.
plugins/anthropic-marketplace/engram/README.md Rewritten from pinned source; examples and integrations unexecuted.
plugins/anthropic-marketplace/engram/skills/cost/SKILL.md Preserved executable agent/prompt contract; prose refresh does not authorize changing agent behavior.
plugins/anthropic-marketplace/engram/skills/mistakes/SKILL.md Preserved executable agent/prompt contract; prose refresh does not authorize changing agent behavior.
plugins/anthropic-marketplace/engram/skills/query/SKILL.md Preserved executable agent/prompt contract; prose refresh does not authorize changing agent behavior.
tests/fixtures/hook-payloads/README.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/memory-md/sample-index.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/mistake-corpus-readme.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/skills/anomaly/SKILL.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/skills/corrupted/SKILL.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/skills/empty-body/SKILL.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/skills/multiline/SKILL.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/skills/normal/SKILL.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.
tests/fixtures/skills/unicode/SKILL.md Preserved executable test fixture or fixture contract; changing it could alter test coverage. No runtime result inferred.

New supporting documents: docs/REFERENCE.md and docs/RESEARCH.md. No original source or protected legal/security file was changed.

Protected-file evidence

  • LICENSE SHA-256 1d16686a13cf73b91280e909e1459e0d1aa43231000ac5d8cf72b3d18ef0b63a.
  • SECURITY.md SHA-256 1287e0547f8c4ca298fda25d977da4b1bcf21946723c14502bbab1455bd94c08.
  • CHANGELOG.md SHA-256 771f49e8f8225b5dd0c6033f5400ace08edb78df865e2c24dd6c91fae734c94c.
  • extensions/vscode/LICENSE SHA-256 1d16686a13cf73b91280e909e1459e0d1aa43231000ac5d8cf72b3d18ef0b63a.

Remaining verification

Clean installation, useful-command execution, malformed input, side-effect boundaries, platform compatibility and end-to-end tests remain unverified. Package-registry availability and live API destinations were not checked. No performance, customer-adoption, compliance or production-readiness claim is made.

Captured evidence index

Additional authored documents

  • docs/PORTFOLIO-GUIDE.md — current source-backed guide/entrypoint.

Tree files outside the captured text set

These paths were mapped but their contents were not acquired in this research pass:

  • .cursorrules
  • .gitignore
  • adapters/continue/.npmignore
  • adapters/continue/package-lock.json
  • assets/banner-v3.png
  • assets/banner.png
  • assets/screenshots/01-overview.png
  • assets/screenshots/02-sessions.png
  • assets/screenshots/03-activity.png
  • assets/screenshots/04-files.png
  • assets/screenshots/05-graph.png
  • assets/screenshots/06-providers.png
  • bench/results/TEMPLATE.csv
  • docs/demos/before-after.cast
  • docs/demos/captions.vtt
  • docs/demos/chapters.vtt
  • docs/demos/poster.svg
  • docs/demos/v4-skill-pack.cast
  • docs/engram-sentinel-ecosystem.pdf
  • extensions/vscode/.gitignore
  • extensions/vscode/.vscodeignore
  • extensions/vscode/assets/icon.png
  • package-lock.json
  • scripts/mcp-engram

Additional integration review

The active installation, integration, editor, provider, benchmark, demonstration and comparison guides were rewritten. The Continue adapter's HTTP fallback omits authentication; the VS Code dashboard command invokes dashboard while the engine declares ui. The benchmark runner derives comparisons from fixture expected_tokens. These are source findings, not executed failures. See the rewritten guides for pinned implementation citations. Historical media scene copy remains explicitly deferred pending a coordinated asset revision.

Expanded HTML review

The acquisition now includes 332 of 332 eligible text files. Six HTML documentation/media pages were inspected; the seventh HTML file, assets/banner.html, is a decorative banner source retained without a runtime/UI change. Four active guides are mapped to rewritten Markdown for the root renderer; generation and visual verification are separate delivery steps.

Existing HTML Disposition Markdown authority
docs/install.html Replace active guide through branded HTML rendering llms-install.md
docs/engram-user-manual.html Replace active guide through branded HTML rendering docs/USER-MANUAL.md
docs/engram-integration-guide.html Replace active guide through branded HTML rendering docs/INTEGRATION.md
docs/engram-sentinel-ecosystem.html Replace active guide through branded HTML rendering docs/SENTINEL.md
docs/demos/hf/index.html Historical v2.0.2 animated scene composition; preserve with scene-table/captions pending coordinated media revision. Quantitative claims are not validated. docs/demos/README.md records historical status
docs/demos/showcase.html Historical v2.0.2 player/storyboard and render source; preserve with captions/video pending coordinated media revision. Quantitative claims are not validated. docs/demos/README.md records historical status

Additional knowledge retained: skills indexing, generated-instruction targets, MEMORY.md synchronization, Git hook behavior/limitations, troubleshooting, scoped uninstall, supported library exports, hook coexistence, current lifecycle events, read gates and guard defaults. Old getStore/getFileContext package-root imports, gen --memory-md, fixed savings figures and universal no-network claims were not carried forward.

The Git-hook template calls init --quiet, which is absent from the inspected parser, and its fallback global package path uses engram rather than engramx. The mistake-guard implementation defaults to permissive, contrary to stale comments; 0 disables it and 2 selects strict mode. These findings are static, not executed failures.

Newly captured HTML evidence