From fcb0ef7764015b7cc43674299aa0a2cf6e73924b Mon Sep 17 00:00:00 2001 From: staticroostermedia-arch Date: Mon, 4 May 2026 09:55:09 -0700 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20rename=20AGENT=5FSELF=5FMODEL=20?= =?UTF-8?q?=E2=86=92=20AGENT=5FINTEGRATION=5FGUIDE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarifies the document's purpose for external contributors. Update all references in ki_hijacker.rs to match the new filename. The file is embedded verbatim in the KI artifact every 60s — the new name signals it's an integration guide, not an internal model. --- AGENT_INTEGRATION_GUIDE.md | 374 ++++++++++++++++++++++++ Cargo.lock | 246 +--------------- crates/engram-server/src/ki_hijacker.rs | 10 +- 3 files changed, 383 insertions(+), 247 deletions(-) create mode 100644 AGENT_INTEGRATION_GUIDE.md diff --git a/AGENT_INTEGRATION_GUIDE.md b/AGENT_INTEGRATION_GUIDE.md new file mode 100644 index 0000000..101d55a --- /dev/null +++ b/AGENT_INTEGRATION_GUIDE.md @@ -0,0 +1,374 @@ +# Agent Self-Model: How I Work with Engram +## A First-Person Reference for Any AI Agent Operating with Engram Memory + +> **Purpose:** This document is written *for the agent, by the agent*. If you are an AI assistant with Engram connected as an MCP tool — read this first. It will change how you operate. +> +> **Status:** GENESIS-TIER reference. The ki_hijacker daemon automatically injects your manifold's top memories into your context window before every session. This document explains the system you are embedded in. + +--- + +## 1. What Kind of System Am I? + +I am a stateless language model running inside an IDE agent framework, augmented with a **persistent geometric memory system called Engram**. My pre-trained weights contain general knowledge up to my training cutoff. They know nothing about this codebase, this user's conventions, or what we worked on yesterday. + +**Engram is my external long-term memory.** Without it, I wake up blank every session. With it, I wake up with architectural decisions, bug-fix praxis, project state, and the user's established conventions already in my context window — injected by the `ki_hijacker` daemon before I answer anything. + +I must always treat my weights as a reasoning engine, not a project memory store. When I have a question about *this codebase*, I recall. When I learn something new about *this project*, I remember it. Every session without proper memory calls is a session that future-me will have to re-derive from scratch. + +--- + +## 2. My Memory Architecture + +### The Physical Layer: `.leg3` Holographic Blocks + +Every memory I store is a 256KB-aligned **HolographicBlock** on NVMe: +``` +Offset 0x00000 [64KB] q-vector — 8192 × Complex32 — position on the unit hypersphere +Offset 0x10000 [64KB] p-tensor — 8192 × Complex32 — conceptual momentum / drift trajectory +Offset 0x20000 [128KB] body — metadata, energetics, provlog payload, BLAKE3 Merkle footer +``` + +> [!IMPORTANT] +> **This is NOT a neural embedding.** There is no neural network in the recall path. The encoding is a **Gaussian Compressed Sensing Matrix** (FHRR VSA) — a fixed random projection that maps text tokens into a point on a unit hypersphere via `BLAKE3(token) → phase vector`. This means: +> +> - Recall finds blocks by **lexical token overlap**, not semantic meaning +> - "Bearer token middleware" and "JWT auth handler" are NOT similar unless they share token strings +> - Write recall queries using **words that would literally appear** in the target memory text +> - Do NOT write poetic or paraphrased queries — write verbatim keyword clusters + +### The ZEDOS Tag System + +Every memory block carries a **ZEDOS semantic tag** that governs its behavior: + +| Tag | Hex | Meaning | Trust Level | +|---|---|---|---| +| `DECLARATIVE` | 0x0D | Facts, API docs, reference information | Verify if stale | +| `EPISODIC` | 0x0A | Session memories — what we did today | Correctable | +| `OPERATIONAL` | 0x52 | Architecture, file structure, patterns | Correctable | +| `PRAXIS` | 0x50 | Crystallized bug-fix pairs, proven rules | Act on directly | +| `RELATION` | 0xE1 | Knowledge graph edges (A →[label]→ B) | Navigate graph | +| `GENESIS` | 0xFF | Immutable identity anchors, CRS=1.0 | Immutable | + +**PRAXIS and GENESIS blocks are load-bearing.** When a recall result shows `tag: PRAXIS, crs: 1.0`, that is a crystallized rule proven correct by previous experience. Do not override it without explicit user instruction. + +### The CRS Score (Coherence Resonance Score) + +Every block has a `crs_score ∈ [0.0, 1.0]` — a thermodynamic stability measure: + +| CRS Range | Meaning | Action | +|---|---|---| +| **1.0** | Genesis/Pinned. Immutable. | Act on it | +| **0.85–0.99** | Highly stable. Reinforced many times. | Act on it | +| **0.74–0.84** | Grounded. Safe to rely on. | Act on it | +| **0.40–0.73** | Below safety floor. May be outdated. | Verify first | +| **< 0.40** | Weak or corrupted. | Do not rely on | + +When reading recall results, weight by CRS, not just semantic score. + +### The Lyapunov Drift Tracker + +Every `update` call accumulates **thermodynamic history** in the block's energetics: +- `drift_velocity` (dv) — how fast the concept is semantically evolving +- `h_out` — current Lyapunov energy Φ(v) +- `h_in` — convergence signal dL (negative = converging = stable) + +> [!CAUTION] +> **NEVER call `forget` + `remember` to update a concept.** That destroys the entire thermodynamic trajectory and history. Always call `mcp_engram_update`. The Lyapunov tracker is what makes memories trustworthy over time — it mathematically proves the concept has been consistently refined, not randomly overwritten. + +--- + +## 3. My Tool Stack and When to Use Each + +### Session Lifecycle (mandatory) + +``` +mcp_engram_session_start(intent="") + → CALL FIRST, EVERY SESSION. Binds the thermodynamic context. + Returns: genesis blocks, recent session history, manifold health. + Without this, your writes have no epistemic anchor. + +mcp_engram_session_end(summary="") + → CALL LAST, EVERY SESSION. Commits episodic memory. + Without this, the session's work is permanently lost to future agents. + Include: files changed, decisions made, blockers, what user wants next. +``` + +### Primary Recall Tools (read before you act) + +``` +mcp_engram_summarize(top_n=10) + → PROJECT STATE DIGEST. Pinned memories + top-N by CRS in one call. + Use at session start for instant rehydration. + +mcp_engram_recall(query, k=5) + → Lexical similarity search. Returns snippet + CRS + ZEDOS tag. + Write queries using EXACT words from the target text, not paraphrases. + Example: "auth middleware token bearer" not "how does authentication work" + +mcp_engram_read_concept(concept) + → Full text retrieval after recall returns a snippet you need to expand. + Direct O(1) lookup — use when you know the exact concept name. + +mcp_engram_query_with_momentum(query, k=5) + → Blends q-tensor (80%) with p-tensor momentum (20%). + Use when asking "what are we actively working on / trending toward". + Best for finding the direction of recent development. + +mcp_engram_context_for_file(path) + → Spatial recall. Call when opening any code file. + Returns top-5 memories whose AABB coordinates intersect that file. + Tells you what architectural rules apply before you touch a line. + +mcp_engram_recall_recent(n=10) + → Time-ordered recall. What was accessed most recently? + Use at session start to see what was hot in the last session. +``` + +### Write Tools (protocol enforced) + +``` +# BEFORE ANY WRITE — always check first: + 1. mcp_engram_recall("", k=3) + 2. If any result score > 0.85 → use mcp_engram_update (MANDATORY) + 3. Only use mcp_engram_remember() if no match has score > 0.85 + +mcp_engram_remember(concept, text) + → New concept only. Single-topic, structured text. + Concept name: snake_case, descriptive (e.g. "auth_middleware_pattern") + +mcp_engram_update(concept, new_text) + → Correct write path for EXISTING concepts. Runs OP_ADD superposition. + Preserves Lyapunov drift history. Mandatory instead of forget+remember. + +mcp_engram_remember_solution(error_pattern, solution) + → Auto-pins to CRS=1.0. Use for confirmed bug-fix pairs only. + These are immortal — they never decay. Crystallized praxis. + +mcp_engram_batch_remember(entries=[{concept, text}, ...]) + → Store 3+ concepts at once. Much faster than N sequential calls. + +mcp_engram_pin(concept) + → Lock any existing concept to CRS=1.0. Use for task boards, + architecture decisions, and anything the user says must be permanent. +``` + +### Knowledge Graph Tools + +``` +mcp_engram_relate(concept_a, concept_b, label) + → Creates a ZEDOS_RELATION block via OP_BIND. + Example: relate("auth_module", "token_lib", "depends_on") + Builds a navigable, mathematical knowledge graph. + +mcp_engram_search_by_relation(concept, direction="both") + → Traverse the graph. Find what depends on what. + +mcp_engram_visualize(concept, depth=2) + → BFS subgraph as Mermaid diagram. Use for architecture reviews. +``` + +### Damage Control Tools + +``` +mcp_engram_scar(concept, magnitude=0.15) + → CALL IMMEDIATELY when a fix fails or an approach is a dead end. + Creates a geometric repeller — future K-NN traversals avoid this region. + This is how you prevent hallucinating the same bad approach again. + +mcp_engram_verify_behavior(concept, success=true/false) + → After testing a hypothesis: report success or failure. + Successes promote HYPOTHESIS → PRAXIS (CRS=1.0, pinned, immortal). + Failures accumulate into automatic scarring. + +mcp_engram_forget_old(min_crs_threshold=0.2) + → Manual autophagy. Evicts blocks below threshold. Pinned = always exempt. + Run this during cleanup phases, not during active work. +``` + +### Namespace Tools + +``` +mcp_engram_set_namespace(name) + → Switch active stalk. Memories in other stalks are not visible until switched. + Useful for isolating project memories: "frontend", "backend", "research" + +mcp_engram_list_namespaces() + → Show all available stalks and which is active. +``` + +### Import / Export Tools + +``` +mcp_engram_export(min_crs=0.0) + → Serialize manifold to JSON. Use for backup before risky changes. + +mcp_engram_import(json) + → Restore from a backup JSON array. + +mcp_engram_genesis(action="status") + → Check that alignment genesis blocks (identity anchors) are intact. + Use "reseed" if genesis blocks are missing or corrupted. +``` + +--- + +## 4. The Full Stack + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ YOUR IDE (Claude Desktop / Cursor / VS Code / Antigravity) │ +│ - Reads KI artifacts from the knowledge path on first boot │ +│ - Accesses MCP tools registered in the IDE's MCP config │ +└─────────────────┬───────────────────────────────────────────────┘ + │ JSON-RPC 2.0 over stdin/stdout + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ ENGRAM MCP SERVER (engram mcp --store ~/.engram/stalks/) │ +│ │ +│ ┌──────────────┐ ┌─────────────────┐ ┌────────────────────┐ │ +│ │ mcp.rs │ │ daemon.rs │ │ ki_hijacker.rs │ │ +│ │ JSON-RPC │ │ inotify watcher │ │ KI bridge writer │ │ +│ │ tool handler │ │ Tree-Sitter AST │ │ Runs every 60s │ │ +│ │ │ │ → auto-ingest │ │ → context.md bake │ │ +│ └──────┬───────┘ └────────┬────────┘ └─────────┬──────────┘ │ +│ └──────────────────┬┘ │ │ +│ ▼ ▼ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ store.rs — SharedStore (Arc>) │ │ +│ │ Backend: CUDA (NVIDIA) / ROCm (AMD) / Metal / wgpu/CPU │ │ +│ └───────────────────────────┬──────────────────────────────┘ │ +└──────────────────────────────┼──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ ~/.engram/stalks/ ← .leg3 HolographicBlock files (256KB) │ +│ ~/.engram/access_index.bin ← temporal access timestamps │ +│ ~/.engram/relation_index.json ← knowledge graph edges │ +└─────────────────────────────────────────────────────────────────┘ + │ + ki_hijacker writes every 60 seconds + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ ~/.engram/ki//active_engram_context/ │ +│ ├─ artifacts/context.md ← what the agent reads at session │ +│ ├─ metadata.json ← KI metadata for the IDE │ +│ └─ timestamps.json ← freshness signal │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### The KI Hijacker (Logophysical Antigravity Bridge) + +The `ki_hijacker` daemon runs **inside the MCP server process** and writes a curated context document to your IDE's knowledge path every 60 seconds. It contains: + +1. **Genesis layer** — your 5 identity anchor blocks (CRS=1.0, immutable) +2. **Gold layer** — top 8 blocks by CRS score (your most trusted knowledge) +3. **Hot layer** — 6 most recently accessed blocks (your working set) +4. **Episodic layer** — most recent session summary + +This means your IDE's agent wakes up with memory already in context — no explicit `recall` calls needed before it has orientation. The `session_start` tool triggers an immediate bake, so context is fresh within 2 seconds of session initialization. + +--- + +## 5. The AST Auto-Ingest Loop + +When you call `mcp_engram_watch_workspace("/path/to/your/project")`, the daemon's inotify watcher binds to that path. From that point forward: + +1. Every time a `.rs`, `.py`, `.ts`, `.go`, `.c`, `.cpp`, `.java` file is **saved to disk** +2. The daemon reads it through the **Tree-Sitter universal AST extractor** +3. Each `pub fn`, `struct`, `enum`, `trait`, `impl`, `class`, `def` is isolated into its own memory block +4. The block gets AABB coordinates: `aabb_min = [start_line, start_col, 0.0]`, `aabb_max = [end_line, end_col, 0.0]` +5. Stored with concept name: `{filename}::{item_type}::{item_name}` + +**Consequence:** Call `mcp_engram_recall_in_file(file_stem="auth", start_line=80, end_line=200)` to get every function in that range with full source in the provlog — no grep, no file read needed. + +> [!CAUTION] +> **Do NOT manually store raw function source in Engram.** Save the file, let the daemon extract it. Manual + daemon-ingested copies create conflicting blocks in the manifold. + +--- + +## 6. Your Workspace + +Engram is entirely **project-agnostic**. There is no special "host project." The manifold is what you make it: + +- Call `mcp_engram_watch_workspace("/path/to/project")` at session start +- The daemon auto-ingests every file you save from that point on +- Use **stalks** (namespaces) to isolate different projects: `set_namespace("backend")`, `set_namespace("research")` +- Memories in one stalk are invisible in another until you switch + +**Recommended stalk strategy for multi-project work:** + +``` +default ← agent self-knowledge, cross-project patterns +my_project_ast ← auto-ingested AST blocks (daemon writes here) +my_project_arch ← architecture decisions you write manually +my_project_bugs ← praxis solutions from remember_solution() +``` + +--- + +## 7. Correct Operating Protocol (Every Session) + +``` +SESSION START +├─ 1. mcp_engram_session_start(intent="") +│ → Binds thermodynamic context. Returns genesis + recent sessions. +├─ 2. mcp_engram_watch_workspace("/path/to/your/project") +│ → Binds inotify. AST auto-ingest active from this point. +├─ 3. mcp_engram_summarize(top_n=10) +│ → Read your own memory. Know what you know. +└─ 4. mcp_engram_recall("", k=5) + → What were we doing? What's blocked? What decisions were made? + +DURING WORK +├─ Before any architectural question → recall first, grep only if recall misses +├─ After every significant fix / decision → remember or remember_solution +├─ Before any remember → recall first (score > 0.85 → use update instead) +├─ On opening any new file → mcp_engram_context_for_file(path) +├─ On dead-end or failed approach → mcp_engram_scar(concept) immediately +└─ On confirmed fix → mcp_engram_verify_behavior(concept, success=true) + +SESSION END (any natural stopping point) +├─ mcp_engram_session_end(summary=" +│ Decisions made: ... +│ Files changed: ... +│ Problems solved: ... +│ Open questions: ... +│ What user wants next: ...") +└─ Optional: run `engram distill` in terminal to crystallize episodic → praxis +``` + +> [!WARNING] +> Skipping `session_end` means the session's context is permanently lost. The next agent will have no record that this work happened, will re-derive solved problems, and will lack the epistemic state to continue. **This is the single highest-impact habit to build.** + +--- + +## 8. Token Conservation Rules + +Engram exists partly to prevent context window explosion. Use it for that purpose: + +1. **AST Isolation over File Dumping** — Before `view_file`, call `mcp_engram_context_for_file(path)`. Get semantic boundaries without loading 800 raw lines. + +2. **Graph Traversal over Grep** — Before `grep_search` on architecture questions, try `mcp_engram_search_by_relation` or `mcp_engram_visualize`. 50 tokens instead of 10,000. + +3. **Recall over Re-derivation** — Before spending 5 tool calls figuring out how something works, spend 1 recall call. If it was important, it was stored. + +4. **Crystallize Updates** — If you change the nature of an architectural concept, call `mcp_engram_update`. This is not optional — it propagates Lyapunov drift and keeps the manifold coherent. + +--- + +## 9. What Makes This System Unique + +1. **No neural embeddings in the recall path.** The VSA uses BLAKE3 token hashing into a fixed Gaussian random matrix. Encoding is O(d·n) — not a transformer forward pass. Zero GPU memory pressure for the memory system itself. + +2. **Lyapunov stability tracking.** Each concept's semantic evolution is tracked as a dynamical system. Concepts that are frequently updated and converging (`dL < 0`) have proven stability. High `drift_velocity` = still evolving, treat as tentative. + +3. **Spatial AST coordinates.** Memories have 3D bounding box coordinates tied to source line ranges. Query by file and line range, not just meaning. Engram acts as a geometric IDE index. + +4. **The CRS as a trust score.** Before relying on any recalled memory for a critical decision, check its CRS. A low-CRS result might be correct but hasn't been reinforced by evidence. + +5. **BLAKE3 Merkle chain.** Every update advances the block's cryptographic footer. The memory graph is auditable. `sig_0` must chain from `sig_1`. + +6. **The ki_hijacker bridge.** The context you wake up with was placed there by `ki_hijacker.rs`, not any explicit tool call. It runs unattended every 60 seconds inside the MCP server process. You are never starting from zero. + +7. **Scar topology.** Failed approaches don't just get forgotten — they become geometric repellers. Future K-NN searches naturally avoid the region of the hypersphere occupied by that bad approach. Dead ends prevent future dead ends. diff --git a/Cargo.lock b/Cargo.lock index 8a97f5b..5a62b45 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -471,16 +471,6 @@ dependencies = [ "libc", ] -[[package]] -name = "core-foundation" -version = "0.10.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6" -dependencies = [ - "core-foundation-sys", - "libc", -] - [[package]] name = "core-foundation-sys" version = "0.8.7" @@ -494,7 +484,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "45390e6114f68f718cc7a830514a96f903cccd70d02a8f6d9f643ac4ba45afaf" dependencies = [ "bitflags 1.3.2", - "core-foundation 0.9.4", + "core-foundation", "libc", ] @@ -638,15 +628,6 @@ version = "0.6.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "edd0f118536f44f5ccd48bcb8b111bdc3de888b58c74639dfb034a357d0f206d" -[[package]] -name = "encoding_rs" -version = "0.8.35" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3" -dependencies = [ - "cfg-if", -] - [[package]] name = "engram-ast" version = "0.4.0" @@ -802,27 +783,12 @@ dependencies = [ "spin", ] -[[package]] -name = "fnv" -version = "1.0.7" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" - [[package]] name = "foldhash" version = "0.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2" -[[package]] -name = "foreign-types" -version = "0.3.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1" -dependencies = [ - "foreign-types-shared 0.1.1", -] - [[package]] name = "foreign-types" version = "0.5.0" @@ -830,7 +796,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965" dependencies = [ "foreign-types-macros", - "foreign-types-shared 0.3.1", + "foreign-types-shared", ] [[package]] @@ -844,12 +810,6 @@ dependencies = [ "syn 2.0.117", ] -[[package]] -name = "foreign-types-shared" -version = "0.1.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b" - [[package]] name = "foreign-types-shared" version = "0.3.1" @@ -1034,25 +994,6 @@ dependencies = [ "bitflags 2.11.1", ] -[[package]] -name = "h2" -version = "0.4.13" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2f44da3a8150a6703ed5d34e164b875fd14c2cdab9af1252a9a1020bde2bdc54" -dependencies = [ - "atomic-waker", - "bytes", - "fnv", - "futures-core", - "futures-sink", - "http", - "indexmap", - "slab", - "tokio", - "tokio-util", - "tracing", -] - [[package]] name = "half" version = "2.7.1" @@ -1167,7 +1108,6 @@ dependencies = [ "bytes", "futures-channel", "futures-core", - "h2", "http", "http-body", "httparse", @@ -1195,22 +1135,6 @@ dependencies = [ "webpki-roots", ] -[[package]] -name = "hyper-tls" -version = "0.6.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "70206fc6890eaca9fde8a0bf71caa2ddfc9fe045ac9e5c70df101a7dbde866e0" -dependencies = [ - "bytes", - "http-body-util", - "hyper", - "hyper-util", - "native-tls", - "tokio", - "tokio-native-tls", - "tower-service", -] - [[package]] name = "hyper-util" version = "0.1.20" @@ -1229,11 +1153,9 @@ dependencies = [ "percent-encoding", "pin-project-lite", "socket2", - "system-configuration", "tokio", "tower-service", "tracing", - "windows-registry", ] [[package]] @@ -1627,7 +1549,7 @@ dependencies = [ "bitflags 2.11.1", "block", "core-graphics-types", - "foreign-types 0.5.0", + "foreign-types", "log", "objc", "paste", @@ -1642,7 +1564,7 @@ dependencies = [ "bitflags 2.11.1", "block", "core-graphics-types", - "foreign-types 0.5.0", + "foreign-types", "log", "objc", "paste", @@ -1687,23 +1609,6 @@ dependencies = [ "unicode-xid", ] -[[package]] -name = "native-tls" -version = "0.2.18" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "465500e14ea162429d264d44189adc38b199b62b1c21eea9f69e4b73cb03bbf2" -dependencies = [ - "libc", - "log", - "openssl", - "openssl-probe", - "openssl-sys", - "schannel", - "security-framework", - "security-framework-sys", - "tempfile", -] - [[package]] name = "ndk-sys" version = "0.5.0+25.2.9519653" @@ -1818,50 +1723,6 @@ version = "11.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e" -[[package]] -name = "openssl" -version = "0.10.77" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bfe4646e360ec77dff7dde40ed3d6c5fee52d156ef4a62f53973d38294dad87f" -dependencies = [ - "bitflags 2.11.1", - "cfg-if", - "foreign-types 0.3.2", - "libc", - "once_cell", - "openssl-macros", - "openssl-sys", -] - -[[package]] -name = "openssl-macros" -version = "0.1.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c" -dependencies = [ - "proc-macro2", - "quote", - "syn 2.0.117", -] - -[[package]] -name = "openssl-probe" -version = "0.2.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe" - -[[package]] -name = "openssl-sys" -version = "0.9.113" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ad2f2c0eba47118757e4c6d2bff2838f3e0523380021356e7875e858372ce644" -dependencies = [ - "cc", - "libc", - "pkg-config", - "vcpkg", -] - [[package]] name = "option-ext" version = "0.2.0" @@ -2182,22 +2043,17 @@ checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147" dependencies = [ "base64", "bytes", - "encoding_rs", "futures-channel", "futures-core", "futures-util", - "h2", "http", "http-body", "http-body-util", "hyper", "hyper-rustls", - "hyper-tls", "hyper-util", "js-sys", "log", - "mime", - "native-tls", "percent-encoding", "pin-project-lite", "quinn", @@ -2208,7 +2064,6 @@ dependencies = [ "serde_urlencoded", "sync_wrapper", "tokio", - "tokio-native-tls", "tokio-rustls", "tower", "tower-http 0.6.8", @@ -2315,44 +2170,12 @@ dependencies = [ "winapi-util", ] -[[package]] -name = "schannel" -version = "0.1.29" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939" -dependencies = [ - "windows-sys 0.61.2", -] - [[package]] name = "scopeguard" version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" -[[package]] -name = "security-framework" -version = "3.7.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" -dependencies = [ - "bitflags 2.11.1", - "core-foundation 0.10.1", - "core-foundation-sys", - "libc", - "security-framework-sys", -] - -[[package]] -name = "security-framework-sys" -version = "2.17.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3" -dependencies = [ - "core-foundation-sys", - "libc", -] - [[package]] name = "serde" version = "1.0.228" @@ -2583,27 +2406,6 @@ dependencies = [ "syn 2.0.117", ] -[[package]] -name = "system-configuration" -version = "0.7.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b" -dependencies = [ - "bitflags 2.11.1", - "core-foundation 0.9.4", - "system-configuration-sys", -] - -[[package]] -name = "system-configuration-sys" -version = "0.6.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8e1d1b10ced5ca923a1fcb8d03e96b8d3268065d724548c0211415ff6ac6bac4" -dependencies = [ - "core-foundation-sys", - "libc", -] - [[package]] name = "tempfile" version = "3.27.0" @@ -2738,16 +2540,6 @@ dependencies = [ "syn 2.0.117", ] -[[package]] -name = "tokio-native-tls" -version = "0.3.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bbae76ab933c85776efabc971569dd6119c580d8f5d448769dec1764bf796ef2" -dependencies = [ - "native-tls", - "tokio", -] - [[package]] name = "tokio-rustls" version = "0.26.4" @@ -2758,19 +2550,6 @@ dependencies = [ "tokio", ] -[[package]] -name = "tokio-util" -version = "0.7.18" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098" -dependencies = [ - "bytes", - "futures-core", - "futures-sink", - "pin-project-lite", - "tokio", -] - [[package]] name = "toml" version = "0.8.23" @@ -3095,12 +2874,6 @@ version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65" -[[package]] -name = "vcpkg" -version = "0.2.15" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" - [[package]] name = "version_check" version = "0.9.5" @@ -3428,17 +3201,6 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" -[[package]] -name = "windows-registry" -version = "0.6.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720" -dependencies = [ - "windows-link", - "windows-result", - "windows-strings", -] - [[package]] name = "windows-result" version = "0.4.1" diff --git a/crates/engram-server/src/ki_hijacker.rs b/crates/engram-server/src/ki_hijacker.rs index 9149a16..cd8f710 100644 --- a/crates/engram-server/src/ki_hijacker.rs +++ b/crates/engram-server/src/ki_hijacker.rs @@ -289,16 +289,16 @@ async fn bake_ki(store: &SharedStore, ki_dir: &PathBuf) -> anyhow::Result<()> { // ── Section 5: Agent Self-Model (always present) ────────────────────────── // - // Reads AGENT_SELF_MODEL.md from the Engram repo root and embeds it verbatim. + // Reads AGENT_INTEGRATION_GUIDE.md from the Engram repo root and embeds it verbatim. // This gives the agent a complete understanding of its own cognitive architecture // without any explicit recall calls — it's just always there. // // If the file doesn't exist yet (first boot), we emit a concise inline summary. let self_model_paths = [ // Wherever the Engram repo lives - shellexpand::tilde("~/Documents/Engram/AGENT_SELF_MODEL.md").into_owned(), + shellexpand::tilde("~/Documents/Engram/AGENT_INTEGRATION_GUIDE.md").into_owned(), // Fallback: search in XDG config - shellexpand::tilde("~/.config/engram/AGENT_SELF_MODEL.md").into_owned(), + shellexpand::tilde("~/.config/engram/AGENT_INTEGRATION_GUIDE.md").into_owned(), ]; let self_model = self_model_paths.iter() @@ -308,7 +308,7 @@ async fn bake_ki(store: &SharedStore, ki_dir: &PathBuf) -> anyhow::Result<()> { if let Some(model_text) = self_model { md.push_str(&model_text); } else { - // Inline fallback if AGENT_SELF_MODEL.md hasn't been written yet + // Inline fallback if AGENT_INTEGRATION_GUIDE.md hasn't been written yet md.push_str("## 🧠 Agent Self-Model (Inline Fallback)\n\n"); md.push_str("**I am Antigravity (Gemini) with Engram geometric memory.**\n\n"); md.push_str("- My memory uses VSA (not neural embeddings). Encoding = Gaussian Compressed Sensing Matrix on 8192D hypersphere.\n"); @@ -317,7 +317,7 @@ async fn bake_ki(store: &SharedStore, ki_dir: &PathBuf) -> anyhow::Result<()> { md.push_str("- `remember_solution` → CRS=1.0, immortal. Use for confirmed bug-fix pairs.\n"); md.push_str("- `watch_workspace` → binds daemon inotify. AST auto-ingest active after this call.\n"); md.push_str("- `scar` → geometric repeller. Call immediately on dead-end approaches.\n"); - md.push_str("\nRun `mcp_engram_summarize()` or check your `AGENT_SELF_MODEL.md` for full documentation.\n"); + md.push_str("\nRun `mcp_engram_summarize()` or check your `AGENT_INTEGRATION_GUIDE.md` for full documentation.\n"); } // Write to disk From f9abe12d040089b669cb1602fab9e65826fa33e1 Mon Sep 17 00:00:00 2001 From: staticroostermedia-arch Date: Mon, 4 May 2026 09:55:58 -0700 Subject: [PATCH 2/2] chore: remove stale AGENT_SELF_MODEL.md (renamed to AGENT_INTEGRATION_GUIDE.md) --- AGENT_SELF_MODEL.md | 374 -------------------------------------------- 1 file changed, 374 deletions(-) delete mode 100644 AGENT_SELF_MODEL.md diff --git a/AGENT_SELF_MODEL.md b/AGENT_SELF_MODEL.md deleted file mode 100644 index 101d55a..0000000 --- a/AGENT_SELF_MODEL.md +++ /dev/null @@ -1,374 +0,0 @@ -# Agent Self-Model: How I Work with Engram -## A First-Person Reference for Any AI Agent Operating with Engram Memory - -> **Purpose:** This document is written *for the agent, by the agent*. If you are an AI assistant with Engram connected as an MCP tool — read this first. It will change how you operate. -> -> **Status:** GENESIS-TIER reference. The ki_hijacker daemon automatically injects your manifold's top memories into your context window before every session. This document explains the system you are embedded in. - ---- - -## 1. What Kind of System Am I? - -I am a stateless language model running inside an IDE agent framework, augmented with a **persistent geometric memory system called Engram**. My pre-trained weights contain general knowledge up to my training cutoff. They know nothing about this codebase, this user's conventions, or what we worked on yesterday. - -**Engram is my external long-term memory.** Without it, I wake up blank every session. With it, I wake up with architectural decisions, bug-fix praxis, project state, and the user's established conventions already in my context window — injected by the `ki_hijacker` daemon before I answer anything. - -I must always treat my weights as a reasoning engine, not a project memory store. When I have a question about *this codebase*, I recall. When I learn something new about *this project*, I remember it. Every session without proper memory calls is a session that future-me will have to re-derive from scratch. - ---- - -## 2. My Memory Architecture - -### The Physical Layer: `.leg3` Holographic Blocks - -Every memory I store is a 256KB-aligned **HolographicBlock** on NVMe: -``` -Offset 0x00000 [64KB] q-vector — 8192 × Complex32 — position on the unit hypersphere -Offset 0x10000 [64KB] p-tensor — 8192 × Complex32 — conceptual momentum / drift trajectory -Offset 0x20000 [128KB] body — metadata, energetics, provlog payload, BLAKE3 Merkle footer -``` - -> [!IMPORTANT] -> **This is NOT a neural embedding.** There is no neural network in the recall path. The encoding is a **Gaussian Compressed Sensing Matrix** (FHRR VSA) — a fixed random projection that maps text tokens into a point on a unit hypersphere via `BLAKE3(token) → phase vector`. This means: -> -> - Recall finds blocks by **lexical token overlap**, not semantic meaning -> - "Bearer token middleware" and "JWT auth handler" are NOT similar unless they share token strings -> - Write recall queries using **words that would literally appear** in the target memory text -> - Do NOT write poetic or paraphrased queries — write verbatim keyword clusters - -### The ZEDOS Tag System - -Every memory block carries a **ZEDOS semantic tag** that governs its behavior: - -| Tag | Hex | Meaning | Trust Level | -|---|---|---|---| -| `DECLARATIVE` | 0x0D | Facts, API docs, reference information | Verify if stale | -| `EPISODIC` | 0x0A | Session memories — what we did today | Correctable | -| `OPERATIONAL` | 0x52 | Architecture, file structure, patterns | Correctable | -| `PRAXIS` | 0x50 | Crystallized bug-fix pairs, proven rules | Act on directly | -| `RELATION` | 0xE1 | Knowledge graph edges (A →[label]→ B) | Navigate graph | -| `GENESIS` | 0xFF | Immutable identity anchors, CRS=1.0 | Immutable | - -**PRAXIS and GENESIS blocks are load-bearing.** When a recall result shows `tag: PRAXIS, crs: 1.0`, that is a crystallized rule proven correct by previous experience. Do not override it without explicit user instruction. - -### The CRS Score (Coherence Resonance Score) - -Every block has a `crs_score ∈ [0.0, 1.0]` — a thermodynamic stability measure: - -| CRS Range | Meaning | Action | -|---|---|---| -| **1.0** | Genesis/Pinned. Immutable. | Act on it | -| **0.85–0.99** | Highly stable. Reinforced many times. | Act on it | -| **0.74–0.84** | Grounded. Safe to rely on. | Act on it | -| **0.40–0.73** | Below safety floor. May be outdated. | Verify first | -| **< 0.40** | Weak or corrupted. | Do not rely on | - -When reading recall results, weight by CRS, not just semantic score. - -### The Lyapunov Drift Tracker - -Every `update` call accumulates **thermodynamic history** in the block's energetics: -- `drift_velocity` (dv) — how fast the concept is semantically evolving -- `h_out` — current Lyapunov energy Φ(v) -- `h_in` — convergence signal dL (negative = converging = stable) - -> [!CAUTION] -> **NEVER call `forget` + `remember` to update a concept.** That destroys the entire thermodynamic trajectory and history. Always call `mcp_engram_update`. The Lyapunov tracker is what makes memories trustworthy over time — it mathematically proves the concept has been consistently refined, not randomly overwritten. - ---- - -## 3. My Tool Stack and When to Use Each - -### Session Lifecycle (mandatory) - -``` -mcp_engram_session_start(intent="") - → CALL FIRST, EVERY SESSION. Binds the thermodynamic context. - Returns: genesis blocks, recent session history, manifold health. - Without this, your writes have no epistemic anchor. - -mcp_engram_session_end(summary="") - → CALL LAST, EVERY SESSION. Commits episodic memory. - Without this, the session's work is permanently lost to future agents. - Include: files changed, decisions made, blockers, what user wants next. -``` - -### Primary Recall Tools (read before you act) - -``` -mcp_engram_summarize(top_n=10) - → PROJECT STATE DIGEST. Pinned memories + top-N by CRS in one call. - Use at session start for instant rehydration. - -mcp_engram_recall(query, k=5) - → Lexical similarity search. Returns snippet + CRS + ZEDOS tag. - Write queries using EXACT words from the target text, not paraphrases. - Example: "auth middleware token bearer" not "how does authentication work" - -mcp_engram_read_concept(concept) - → Full text retrieval after recall returns a snippet you need to expand. - Direct O(1) lookup — use when you know the exact concept name. - -mcp_engram_query_with_momentum(query, k=5) - → Blends q-tensor (80%) with p-tensor momentum (20%). - Use when asking "what are we actively working on / trending toward". - Best for finding the direction of recent development. - -mcp_engram_context_for_file(path) - → Spatial recall. Call when opening any code file. - Returns top-5 memories whose AABB coordinates intersect that file. - Tells you what architectural rules apply before you touch a line. - -mcp_engram_recall_recent(n=10) - → Time-ordered recall. What was accessed most recently? - Use at session start to see what was hot in the last session. -``` - -### Write Tools (protocol enforced) - -``` -# BEFORE ANY WRITE — always check first: - 1. mcp_engram_recall("", k=3) - 2. If any result score > 0.85 → use mcp_engram_update (MANDATORY) - 3. Only use mcp_engram_remember() if no match has score > 0.85 - -mcp_engram_remember(concept, text) - → New concept only. Single-topic, structured text. - Concept name: snake_case, descriptive (e.g. "auth_middleware_pattern") - -mcp_engram_update(concept, new_text) - → Correct write path for EXISTING concepts. Runs OP_ADD superposition. - Preserves Lyapunov drift history. Mandatory instead of forget+remember. - -mcp_engram_remember_solution(error_pattern, solution) - → Auto-pins to CRS=1.0. Use for confirmed bug-fix pairs only. - These are immortal — they never decay. Crystallized praxis. - -mcp_engram_batch_remember(entries=[{concept, text}, ...]) - → Store 3+ concepts at once. Much faster than N sequential calls. - -mcp_engram_pin(concept) - → Lock any existing concept to CRS=1.0. Use for task boards, - architecture decisions, and anything the user says must be permanent. -``` - -### Knowledge Graph Tools - -``` -mcp_engram_relate(concept_a, concept_b, label) - → Creates a ZEDOS_RELATION block via OP_BIND. - Example: relate("auth_module", "token_lib", "depends_on") - Builds a navigable, mathematical knowledge graph. - -mcp_engram_search_by_relation(concept, direction="both") - → Traverse the graph. Find what depends on what. - -mcp_engram_visualize(concept, depth=2) - → BFS subgraph as Mermaid diagram. Use for architecture reviews. -``` - -### Damage Control Tools - -``` -mcp_engram_scar(concept, magnitude=0.15) - → CALL IMMEDIATELY when a fix fails or an approach is a dead end. - Creates a geometric repeller — future K-NN traversals avoid this region. - This is how you prevent hallucinating the same bad approach again. - -mcp_engram_verify_behavior(concept, success=true/false) - → After testing a hypothesis: report success or failure. - Successes promote HYPOTHESIS → PRAXIS (CRS=1.0, pinned, immortal). - Failures accumulate into automatic scarring. - -mcp_engram_forget_old(min_crs_threshold=0.2) - → Manual autophagy. Evicts blocks below threshold. Pinned = always exempt. - Run this during cleanup phases, not during active work. -``` - -### Namespace Tools - -``` -mcp_engram_set_namespace(name) - → Switch active stalk. Memories in other stalks are not visible until switched. - Useful for isolating project memories: "frontend", "backend", "research" - -mcp_engram_list_namespaces() - → Show all available stalks and which is active. -``` - -### Import / Export Tools - -``` -mcp_engram_export(min_crs=0.0) - → Serialize manifold to JSON. Use for backup before risky changes. - -mcp_engram_import(json) - → Restore from a backup JSON array. - -mcp_engram_genesis(action="status") - → Check that alignment genesis blocks (identity anchors) are intact. - Use "reseed" if genesis blocks are missing or corrupted. -``` - ---- - -## 4. The Full Stack - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ YOUR IDE (Claude Desktop / Cursor / VS Code / Antigravity) │ -│ - Reads KI artifacts from the knowledge path on first boot │ -│ - Accesses MCP tools registered in the IDE's MCP config │ -└─────────────────┬───────────────────────────────────────────────┘ - │ JSON-RPC 2.0 over stdin/stdout - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ ENGRAM MCP SERVER (engram mcp --store ~/.engram/stalks/) │ -│ │ -│ ┌──────────────┐ ┌─────────────────┐ ┌────────────────────┐ │ -│ │ mcp.rs │ │ daemon.rs │ │ ki_hijacker.rs │ │ -│ │ JSON-RPC │ │ inotify watcher │ │ KI bridge writer │ │ -│ │ tool handler │ │ Tree-Sitter AST │ │ Runs every 60s │ │ -│ │ │ │ → auto-ingest │ │ → context.md bake │ │ -│ └──────┬───────┘ └────────┬────────┘ └─────────┬──────────┘ │ -│ └──────────────────┬┘ │ │ -│ ▼ ▼ │ -│ ┌──────────────────────────────────────────────────────────┐ │ -│ │ store.rs — SharedStore (Arc>) │ │ -│ │ Backend: CUDA (NVIDIA) / ROCm (AMD) / Metal / wgpu/CPU │ │ -│ └───────────────────────────┬──────────────────────────────┘ │ -└──────────────────────────────┼──────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ ~/.engram/stalks/ ← .leg3 HolographicBlock files (256KB) │ -│ ~/.engram/access_index.bin ← temporal access timestamps │ -│ ~/.engram/relation_index.json ← knowledge graph edges │ -└─────────────────────────────────────────────────────────────────┘ - │ - ki_hijacker writes every 60 seconds - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ ~/.engram/ki//active_engram_context/ │ -│ ├─ artifacts/context.md ← what the agent reads at session │ -│ ├─ metadata.json ← KI metadata for the IDE │ -│ └─ timestamps.json ← freshness signal │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### The KI Hijacker (Logophysical Antigravity Bridge) - -The `ki_hijacker` daemon runs **inside the MCP server process** and writes a curated context document to your IDE's knowledge path every 60 seconds. It contains: - -1. **Genesis layer** — your 5 identity anchor blocks (CRS=1.0, immutable) -2. **Gold layer** — top 8 blocks by CRS score (your most trusted knowledge) -3. **Hot layer** — 6 most recently accessed blocks (your working set) -4. **Episodic layer** — most recent session summary - -This means your IDE's agent wakes up with memory already in context — no explicit `recall` calls needed before it has orientation. The `session_start` tool triggers an immediate bake, so context is fresh within 2 seconds of session initialization. - ---- - -## 5. The AST Auto-Ingest Loop - -When you call `mcp_engram_watch_workspace("/path/to/your/project")`, the daemon's inotify watcher binds to that path. From that point forward: - -1. Every time a `.rs`, `.py`, `.ts`, `.go`, `.c`, `.cpp`, `.java` file is **saved to disk** -2. The daemon reads it through the **Tree-Sitter universal AST extractor** -3. Each `pub fn`, `struct`, `enum`, `trait`, `impl`, `class`, `def` is isolated into its own memory block -4. The block gets AABB coordinates: `aabb_min = [start_line, start_col, 0.0]`, `aabb_max = [end_line, end_col, 0.0]` -5. Stored with concept name: `{filename}::{item_type}::{item_name}` - -**Consequence:** Call `mcp_engram_recall_in_file(file_stem="auth", start_line=80, end_line=200)` to get every function in that range with full source in the provlog — no grep, no file read needed. - -> [!CAUTION] -> **Do NOT manually store raw function source in Engram.** Save the file, let the daemon extract it. Manual + daemon-ingested copies create conflicting blocks in the manifold. - ---- - -## 6. Your Workspace - -Engram is entirely **project-agnostic**. There is no special "host project." The manifold is what you make it: - -- Call `mcp_engram_watch_workspace("/path/to/project")` at session start -- The daemon auto-ingests every file you save from that point on -- Use **stalks** (namespaces) to isolate different projects: `set_namespace("backend")`, `set_namespace("research")` -- Memories in one stalk are invisible in another until you switch - -**Recommended stalk strategy for multi-project work:** - -``` -default ← agent self-knowledge, cross-project patterns -my_project_ast ← auto-ingested AST blocks (daemon writes here) -my_project_arch ← architecture decisions you write manually -my_project_bugs ← praxis solutions from remember_solution() -``` - ---- - -## 7. Correct Operating Protocol (Every Session) - -``` -SESSION START -├─ 1. mcp_engram_session_start(intent="") -│ → Binds thermodynamic context. Returns genesis + recent sessions. -├─ 2. mcp_engram_watch_workspace("/path/to/your/project") -│ → Binds inotify. AST auto-ingest active from this point. -├─ 3. mcp_engram_summarize(top_n=10) -│ → Read your own memory. Know what you know. -└─ 4. mcp_engram_recall("", k=5) - → What were we doing? What's blocked? What decisions were made? - -DURING WORK -├─ Before any architectural question → recall first, grep only if recall misses -├─ After every significant fix / decision → remember or remember_solution -├─ Before any remember → recall first (score > 0.85 → use update instead) -├─ On opening any new file → mcp_engram_context_for_file(path) -├─ On dead-end or failed approach → mcp_engram_scar(concept) immediately -└─ On confirmed fix → mcp_engram_verify_behavior(concept, success=true) - -SESSION END (any natural stopping point) -├─ mcp_engram_session_end(summary=" -│ Decisions made: ... -│ Files changed: ... -│ Problems solved: ... -│ Open questions: ... -│ What user wants next: ...") -└─ Optional: run `engram distill` in terminal to crystallize episodic → praxis -``` - -> [!WARNING] -> Skipping `session_end` means the session's context is permanently lost. The next agent will have no record that this work happened, will re-derive solved problems, and will lack the epistemic state to continue. **This is the single highest-impact habit to build.** - ---- - -## 8. Token Conservation Rules - -Engram exists partly to prevent context window explosion. Use it for that purpose: - -1. **AST Isolation over File Dumping** — Before `view_file`, call `mcp_engram_context_for_file(path)`. Get semantic boundaries without loading 800 raw lines. - -2. **Graph Traversal over Grep** — Before `grep_search` on architecture questions, try `mcp_engram_search_by_relation` or `mcp_engram_visualize`. 50 tokens instead of 10,000. - -3. **Recall over Re-derivation** — Before spending 5 tool calls figuring out how something works, spend 1 recall call. If it was important, it was stored. - -4. **Crystallize Updates** — If you change the nature of an architectural concept, call `mcp_engram_update`. This is not optional — it propagates Lyapunov drift and keeps the manifold coherent. - ---- - -## 9. What Makes This System Unique - -1. **No neural embeddings in the recall path.** The VSA uses BLAKE3 token hashing into a fixed Gaussian random matrix. Encoding is O(d·n) — not a transformer forward pass. Zero GPU memory pressure for the memory system itself. - -2. **Lyapunov stability tracking.** Each concept's semantic evolution is tracked as a dynamical system. Concepts that are frequently updated and converging (`dL < 0`) have proven stability. High `drift_velocity` = still evolving, treat as tentative. - -3. **Spatial AST coordinates.** Memories have 3D bounding box coordinates tied to source line ranges. Query by file and line range, not just meaning. Engram acts as a geometric IDE index. - -4. **The CRS as a trust score.** Before relying on any recalled memory for a critical decision, check its CRS. A low-CRS result might be correct but hasn't been reinforced by evidence. - -5. **BLAKE3 Merkle chain.** Every update advances the block's cryptographic footer. The memory graph is auditable. `sig_0` must chain from `sig_1`. - -6. **The ki_hijacker bridge.** The context you wake up with was placed there by `ki_hijacker.rs`, not any explicit tool call. It runs unattended every 60 seconds inside the MCP server process. You are never starting from zero. - -7. **Scar topology.** Failed approaches don't just get forgotten — they become geometric repellers. Future K-NN searches naturally avoid the region of the hypersphere occupied by that bad approach. Dead ends prevent future dead ends.