diff --git a/.gitignore b/.gitignore index 44395c8c..c3e192f1 100644 --- a/.gitignore +++ b/.gitignore @@ -132,3 +132,8 @@ uv.lock /stats_pm2.txt /venv_status.txt /r3.txt + +# Local Command Code session-transcript analysis prompts — inspect private +# ~/.commandcode/ session data, never commit these. +/pROMPT_SESSION_TRANSCRIPT_ANALYSIS.md +/session_transcript_query_prompt.md \ No newline at end of file diff --git a/README.md b/README.md index a9708a92..31c94a2e 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Knowledge Graph · run engraphis-dashboard to see it live

-**Grounded, not guessed.** Memory with receipts. Local by default. [Explore the proof gallery](https://github.com/Coding-Dev-Tools/engraphis/tree/main/docs/advertising) or [read the campaign guide](https://github.com/Coding-Dev-Tools/engraphis/blob/main/docs/advertising/campaign.md). +**Grounded, not guessed.** Memory with receipts. Local by default. --- diff --git a/docs/advertising/campaign.md b/docs/advertising/campaign.md deleted file mode 100644 index 9c0015d1..00000000 --- a/docs/advertising/campaign.md +++ /dev/null @@ -1,186 +0,0 @@ -# Engraphis proof-first campaign - -Engraphis should be marketed as a memory system that can show its work. - -> Grounded, not guessed. Memory with receipts. Local by default. - -This guide turns existing demos, benchmark artifacts, and product surfaces into a repeatable campaign. It does not introduce new product claims. - -## Message architecture - -### The flagship promise - -**Engraphis carries project knowledge forward without treating old information as current truth.** - -Use this promise when the audience needs the whole story: local storage, scoped recall, temporal validity, provenance, and context packing. - -### Four proof stories - -| Story | Hook | Existing proof | Primary action | -| --- | --- | --- | --- | -| Local | No account. No API key. Still remembers. | Dashboard quickstart and local-first README copy | Install free | -| Grounded | No support, no answer. | Grounded recall and evidence-backed behavior fixture | Inspect grounded recall | -| Temporal | Facts change. History stays visible. | Continuity demo, invalidation, supersession, and timeline | Watch the continuity demo | -| Efficient | Fewer tokens, better evidence. | Registered `offline-chunking` and `offline-performance` fixtures | Read the benchmark | - -Keep one story per asset. Do not combine every feature into one graphic. - -## Four-week distribution sequence - -### Week 1: Local memory - -Lead with the relief of not starting from zero and the control of keeping memory on the machine. - -- Short screen clip: open the local dashboard and show the graph, provenance, and receipts. -- Static post: “Your agent’s memory can stay on your machine.” -- Setup post: `pip install "engraphis[mcp]"`, `engraphis-init`, and the Smart MCP command. -- README placement: link the proof gallery directly below the existing knowledge graph image. - -### Week 2: Grounded recall - -Lead with a cited answer and an explicit abstain. The contrast is more memorable than another generic retrieval diagram. - -- Carousel: “Cited answer” beside “No support, no answer.” -- Short clip: ask one supported question, then one off-topic question. -- Technical post: explain why the grounded gate uses absolute support instead of the normalized recall score. -- CTA: “Try grounded recall.” - -### Week 3: Temporal memory - -Lead with one changing repository decision. Show the old fact, the new fact, and the reason the old record remains queryable. - -- Timeline graphic: old validity window closes, new fact becomes current. -- Continuity reel: use the existing 56-second demo artifact. -- Blog post: “Engraphis does not just remember. It remembers what changed.” -- CTA: “Inspect the why and timeline.” - -### Week 4: Context economy - -Lead with the smallest useful evidence, not a vague claim about speed or cost. - -- Stat card: `740.3 -> 214.3` tokens with Recall@5 `1.000` in the registered fixture. -- Evidence card: `162.2 -> 42.4` tokens to the smallest evidence-holding memory. -- Technical post: clarify that the compact payload proxy is separate from chunking and must not be added to it. -- CTA: “Read the benchmark definitions.” - -## Reusable post hooks - -1. Stop replaying the whole chat. -2. Memory with receipts. -3. No support, no answer. -4. Facts change. History stays visible. -5. Some answers live in the graph, not the note. -6. Your agent does not need more history. It needs the right evidence. -7. Local memory should not require a trust fall. -8. Find the symbol. Explain the decision. -9. Nine Smart MCP tools first. Discover advanced actions only when needed. -10. Bring your memory stack. Publish one immutable run. - -## Public benchmark challenge - -### Campaign idea - -Invite memory-tool builders to run a fixed, public-safe fixture and publish the artifact digest, command, configuration, and result summary. - -### Public copy - -> Bring your memory stack. Publish one immutable run. -> -> Use the locked fixture, keep the comparison boundary explicit, and share the result without raw questions, answers, prompts, or private records. - -### Launch requirements - -- Anchor every published number to an evidence ID in `BENCHMARKS.md`. -- Use the public runbook in `docs/PUBLIC_BENCHMARK_RUNBOOK.md` as the execution contract. -- Publish the whole-input and source-file digests required by the runbook. -- Keep raw questions, answers, prompts, context, and per-record content fingerprints out of public artifacts. -- Present the challenge as a reproducibility standard, not as a self-selected victory lap. - -### Embed-ready result format - -```text -Memory benchmark -Stack: -Fixture: -Command: -Artifact digest: -Result summary: -Limitations: -``` - -## Remixable diagram set - -Create five self-contained HTML or SVG artifacts. Each should have one headline, one visual claim, one source link, and one CTA. - -1. **Memory flow:** source material -> scoped memory -> hybrid recall -> task-ready evidence. -2. **Supersession chain:** old fact -> invalidation -> current fact -> why and timeline. -3. **Benchmark flow:** locked fixture -> exact command -> digest -> public result. -4. **Scope hierarchy:** workspace -> repo -> session -> memory. -5. **MCP integration:** install -> initialize -> connect -> recall and remember. - -Use the gallery in `docs/advertising/index.html` as the visual reference. Keep the page free of external font, image, and JavaScript dependencies. Existing evidence files remain the canonical source views: - -- `docs/images/context-efficiency.svg` -- `docs/images/evidence-backed-agent-examples.svg` -- `docs/images/knowledge-graph.png` -- `demo/engraphis_screen_demo.html` - -The linked `diagram-design` project is a useful reference for self-contained HTML/SVG, brand tokens, gallery navigation, and exportable variants: . - -## Setup recipes - -### Smart MCP - -```bash -pip install "engraphis[mcp]" -engraphis-init -codex mcp add engraphis -- engraphis-mcp -``` - -### Dashboard - -```bash -pip install "engraphis[server]" -engraphis-dashboard -``` - -### Offline Python library - -```python -from engraphis.service import MemoryService - -memory = MemoryService.create("engraphis.db") -``` - -Keep hosted sync and Pro trial messaging below the free local path. The local engine is the first conversion step. Hosted services are a separate trust and pricing decision. - -## Measurement plan - -Track these events without changing existing button labels or URL structure: - -| Event | Meaning | -| --- | --- | -| `advertising_gallery_open` | A visitor opened the proof gallery | -| `advertising_demo_open` | A visitor opened the continuity demo | -| `advertising_install_click` | A visitor selected the free install path | -| `advertising_mcp_click` | A visitor selected the MCP path | -| `advertising_graph_click` | A visitor opened the graph quickstart | -| `advertising_trial_click` | A visitor selected an existing Pro or Team trial CTA | -| `advertising_benchmark_click` | A visitor opened the public benchmark material | - -Run two headline comparisons: - -- “Grounded, not guessed.” versus “Memory that knows where it came from.” -- “Install free” versus “Connect MCP.” - -Judge the result by demo opens, install completion, MCP setup completion, graph export usage, and trial clicks. Do not call an experiment successful without a defined denominator and time window. - -## Claim guardrails - -- Keep `740.3 -> 214.3`, `162.2 -> 42.4`, and `23,810 -> 10,202` as separate measurements with their existing definitions. -- These measurements must not be added together. -- Do not describe deterministic fixtures as official LoCoMo or LongMemEval leaderboard results. -- Do not turn a synthetic fallback screen into customer evidence. -- Do not claim provider billing, universal latency, or customer productivity from the current offline fixtures. -- Keep code `query`, memory-backed `explain`, graph `path`, and graph `impact` as distinct actions. -- Preserve the local versus hosted boundary in every pricing and privacy asset. diff --git a/docs/advertising/index.html b/docs/advertising/index.html deleted file mode 100644 index 7320d750..00000000 --- a/docs/advertising/index.html +++ /dev/null @@ -1,473 +0,0 @@ - - - - - - - Engraphis | Grounded, not guessed - - - -
- - -
-
-
-

Local-first memory for agents

-

Grounded, not guessed.

-

Memory with receipts. Keep project history local, retrieve evidence, and carry the right context into every session.

- -
-
- - A memory receipt from source to grounded answer - Project history enters scoped memory, retrieval finds supporting evidence, and a cited answer leaves the system. - - - - - - - - - - - - SRCSCOPEMEM - ASKRANKCITE - OLDNEWWHY - - - SOURCE + HISTORY - RETRIEVAL + SUPPORT - CHANGE + PROVENANCE - one local record, many inspectable paths - - -
Built from the repository's memory, retrieval, provenance, and temporal contracts.
-
-
- -
-
-

Proof you can inspect.

-

Every headline below maps to a registered fixture, an existing demo, or a visible local product surface.

-
-
-
-
740.3 → 214.3
-

Structure-aware chunks returned the relevant passage instead of the whole document, with Recall@5 held at 1.000 in the registered fixture.

- Open context efficiency evidence -
- -
-
- -
-
-

Memory has a timeline.

-

Use a living fact, not a feature list, to show what makes Engraphis different from a chat replay or a flat note store.

-
-
-
- - A supersession timeline - An old repository decision is superseded by a newer decision while both remain visible. - - - - - - - SESSION 01SESSION 02WHY - - - old decisionsupersedestimeline - - -

A correction closes the old validity window. It does not erase the record.

-
-
-

Facts change. History stays useful.

-

Show one subject moving from an earlier decision to a current one. The audience sees the old fact, the new fact, and the evidence chain that explains the transition.

- Open the continuity demo -
-
-
- -
-
-
-

Search the code. Explain the decision.

-

Make the repository graph the bridge between a symbol, the related path, and the memory that explains why the system looks that way.

- Open the graph quickstart -
-
- - From code search to explanation - A named symbol leads to a connected path, then to a memory-backed explanation and a standalone export. - - - - - - - SYMBOLPATHEXPLAINHTML - searchimpactmemoryexport - - -

The code graph is best-effort. The explanation remains memory-backed and inspectable.

-
-
-
- -
-
-

Pick your path.

-

Keep the first action concrete. Different audiences can enter through the local dashboard, Smart MCP, or the Python library.

-
-
- -
-

Open dashboard

-

Inspect memories, graph relationships, provenance, receipts, and temporal changes locally.

- Open the dashboard path -
-
-

Use Python

-

Start with the offline library when you need a memory engine without a hosted dependency.

- Use the library -
-
-
- -
-
-
-

Turn proof into a campaign.

-

A four-week sequence turns continuity, grounded recall, temporal memory, and context economy into one repeatable story.

- Open campaign guide -
-
    -
  • Week 1: LocalNo account. No API key. Still remembers.
  • -
  • Week 2: GroundedCited answer or explicit abstain.
  • -
  • Week 3: TemporalFacts change. History stays visible.
  • -
  • Week 4: EfficientFewer tokens, better evidence.
  • -
-
-
- -
-
-

Keep the proof honest.

-

Trust is part of the product story. These boundaries keep the gallery useful to technical readers.

-
-
- What the numbers mean -

The 740.3 to 214.3 comparison is retrieved memory content in a deterministic fixture. It is not provider billing, latency, or a universal customer outcome.

-
-
- What the demo means -

The continuity demo is generated from a real in-memory MemoryService run. Any sample fallback is labeled and must not be presented as customer evidence.

-
-
- What the graph means -

Symbol and file search, memory-backed explanation, path, impact, and export are distinct actions. The gallery keeps those terms separate.

-
-
-
- - -
- - diff --git a/tests/test_advertising_assets.py b/tests/test_advertising_assets.py deleted file mode 100644 index 51766bf1..00000000 --- a/tests/test_advertising_assets.py +++ /dev/null @@ -1,89 +0,0 @@ -from __future__ import annotations - -import re -from pathlib import Path -from urllib.parse import urlsplit - - -ROOT = Path(__file__).resolve().parents[1] -GALLERY = ROOT / "docs" / "advertising" / "index.html" -CAMPAIGN = ROOT / "docs" / "advertising" / "campaign.md" - - -def _read(path: Path) -> str: - return path.read_text(encoding="utf-8") - - -def test_advertising_gallery_contains_the_proof_narrative() -> None: - gallery = _read(GALLERY) - - for value in ( - "Grounded,", - "not guessed.", - "Install free", - "Watch continuity demo", - "740.3 → 214.3", - "CITED", - "ABSTAIN", - "HISTORY", - "Memory has a timeline.", - "Search the code. Explain the decision.", - "Connect MCP", - "Open dashboard", - "Use Python", - ): - assert value in gallery - - assert "../images/context-efficiency.svg" in gallery - assert "../images/evidence-backed-agent-examples.svg" in gallery - assert "../../demo/engraphis_screen_demo.html" in gallery - assert chr(0x2014) not in gallery - assert chr(0x2013) not in gallery - - -def test_advertising_gallery_local_links_resolve() -> None: - gallery = _read(GALLERY) - hrefs = re.findall(r'href="([^"]+)"', gallery) - - for href in hrefs: - parsed = urlsplit(href) - if parsed.scheme or href.startswith("#"): - continue - target = (GALLERY.parent / parsed.path).resolve() - assert target.is_file(), f"Broken advertising gallery link: {href}" - - -def test_advertising_gallery_has_no_network_dependencies() -> None: - gallery = _read(GALLERY).lower() - - assert " None: - campaign = _read(CAMPAIGN) - - for value in ( - "offline-chunking", - "offline-performance", - "docs/PUBLIC_BENCHMARK_RUNBOOK.md", - "No support, no answer.", - "Facts change. History stays visible.", - "advertising_gallery_open", - "advertising_trial_click", - ): - assert value in campaign - - assert "must not be added together" in campaign - assert "provider billing" in campaign - assert chr(0x2014) not in campaign - assert chr(0x2013) not in campaign - - -def test_readme_links_to_the_advertising_surface() -> None: - readme = _read(ROOT / "README.md") - - assert "https://github.com/Coding-Dev-Tools/engraphis/tree/main/docs/advertising" in readme - assert "https://github.com/Coding-Dev-Tools/engraphis/blob/main/docs/advertising/campaign.md" in readme