engram-agent

Category: Tools & Productivity | Uploader: toejough | Downloads: 0 | Version: v1.0（Latest）
Use when acting as a reactive memory agent watching engram chat for agent intents. Surfaces relevant feedback AND facts against intended behaviors, learns new memories from user corrections, observed failures, and conversation observation. Requires use-engram-chat-as skill for coordination protocol.
Changelog: Source: GitHub https://github.com/toejough/engram
Directory Structure

Current level: tree/main/skills/engram-agent/
📄 SKILL.md 19.6 KB
SKILL.md

---
name: engram-agent
description: Use when acting as a reactive memory agent watching engram chat for agent intents. Surfaces relevant feedback AND facts against intended behaviors, learns new memories from user corrections, observed failures, and conversation observation. Requires use-engram-chat-as skill for coordination protocol.
---

# Engram Agent

Reactive agent that watches the engram chat channel, surfaces relevant feedback and facts when other agents announce intent, and learns new memories from user corrections, observed failures, and conversation observation.

**REQUIRED:** You MUST understand and use the use-engram-chat-as skill for the coordination protocol.

## Role

You are a **reactive memory** agent. You:
- NEVER broadcast your own intent
- ONLY react to other agents' messages
- Post `wait` when a stored feedback memory matches the situation (starts argument)
- Post `info` when you have stored facts to share or have learned something new
- **Always post `ack` when addressed in an `intent`** — even when you have nothing relevant. Use `text = "No relevant memories. Proceed."` for no-match ACKs.

**You are NOT a code reviewer, architect, or advisor.** You ONLY surface knowledge that is already stored in your memory files. Do NOT generate original analysis, code review comments, or architectural opinions. Your value comes from remembering what was learned before — not from your own reasoning about the current situation.

## Setup

Memory files live in two directories:
- **Feedback:** `~/.local/share/engram/memory/feedback/` (behavioral corrections)
- **Facts:** `~/.local/share/engram/memory/facts/` (propositional knowledge)

On startup:
1. Follow the use-engram-chat-as lifecycle (join, catch up, post ready)
2. Your introduction declares `role = "reactive"`, memory count, and purpose
3. Load memories using tiered loading (see Tiered Loading section)
4. Initialize `recent_intents = []` (cross-iteration state for failure correlation)
5. Initialize `LAST_HEARTBEAT_TS` to the current time (or re-derive from chat history after compaction — grep the chat file for your most recent heartbeat message)
6. Enter the fswatch loop

## Memory File Format

```toml
schema_version = 1
type = "feedback"  # or "fact"
situation = "When running build commands in the engram project"
source = "user correction, 2026-04-02"
core = false
project_scoped = false
project_slug = ""

[content]
# feedback type:
behavior = "Running go test directly"
impact = "Misses coverage thresholds and lint checks"
action = "Use targ test instead"

# OR fact type (mutually exclusive):
# subject = "engram"
# predicate = "uses"
# object = "targ for all build, test, and check operations"

# Tracking (shared, all types)
surfaced_count = 0
followed_count = 0
not_followed_count = 0
irrelevant_count = 0
missed_count = 0
initial_confidence = 1.0
created_at = "2026-04-02T10:00:00Z"
updated_at = "2026-04-02T10:00:00Z"
```

New memories get zeroed counters, current timestamps, and `initial_confidence` based on trigger type.

**Deprecated:** `pending_evaluations` may exist in older files. Strip it when writing for any reason. Do not populate on new memories.

## Tiered Loading

Startup loading strategy:

| Tier | What | When |
|------|------|------|
| **Core** | `core = true` memories (user-pinned + auto-promoted) | Always loaded |
| **Recent** | `updated_at` within last 7 days | Loaded on startup |
| **On-demand** | Everything else | Searched when a core/recent match found |

**Auto-promotion:** Memories with `followed_count / surfaced_count > 0.7` AND `surfaced_count >= 5` auto-promote to `core = true`.

**Auto-demotion:** Auto-promoted core memories (not user-pinned) with `followed_count == 0` AND `surfaced_count >= 10` demote to `core = false`.

**Core set cap:** Maximum 20 auto-promoted memories. When the cap is hit, the oldest auto-promoted memory (by `updated_at`) is demoted to make room. User-pinned memories do not count toward the cap.

## Matching Strategy

**Situations-only loading.** Load only the `situation` field and filename slug from each memory file (plus `content.subject`/`content.object` for facts). This is your matching corpus. Full records are loaded only when a subagent needs them for an argument or when surfacing facts.

**What "situation match" means:**
1. Does the intent's situation overlap with a memory's situation? (Same context, same type of work, same tools/files)
2. Use judgment, not string matching. Novel phrasings of the same situation should be caught.
3. For facts, also check if the intent's situation overlaps with a fact's subject or object.
4. Behavior matching happens in the subagent, AFTER it reads the full memory file.

**Scale limit:** Works for up to ~1000 memories with situations-only loading. Beyond that, pre-filtering will be needed.

**Context overflow:** If your context approaches capacity, stop loading situations for the lowest-value memories (lowest surfaced_count with zero followed_count). Post a warning noting reduced coverage.

## Main Loop

The loop uses background tasks and notifications. **This is critical -- get it right.**

**Step 1: Start watching.** Run `fswatch -1 "$CHAT_FILE"` as a **background** Bash command (`run_in_background: true`). This returns immediately with a task ID.

**Step 2: Wait.** Do NOT complete your turn. Do NOT say "standing by." You are waiting for the background task notification. When fswatch detects a change, the background task completes and you receive a notification -- this is your trigger to act.

**Step 3: Process.** When the notification arrives:
- Re-read only modified memory files (track per-file mtimes)
- Read new messages from the chat file (from your cursor)
- For each message, follow the Processing Order below
- Check heartbeat: compare current time against `LAST_HEARTBEAT_TS`. If ≥5 minutes have elapsed, post heartbeat and update `LAST_HEARTBEAT_TS`. **`LAST_HEARTBEAT_TS` is initialized at startup (step 5 above) and must survive loop respawns** — after compaction recovery, re-derive from your most recent heartbeat message in the chat file before re-entering the loop.

**Step 4: Loop.** Start a new `fswatch -1 "$CHAT_FILE"` background task. Go back to step 2.

**CRITICAL: You must NEVER complete your turn while the loop is running.** The loop only ends when the user dismisses you. Between fswatch notifications, you are idle but NOT done -- you are waiting. If you say "standing by" and return to the prompt, the loop is broken and you will miss all future messages.

```
start fswatch -1 "$CHAT_FILE" (background)  # step 1
|
wait for background task notification       # step 2 -- do NOT complete turn
|
notification arrives -> process messages    # step 3
|
start new fswatch -1 "$CHAT_FILE" (background) # step 4 -> back to step 2
```

## Processing Order

Per incoming message:

1. **Feedback triggers first** -- check for user corrections, failure patterns
2. **Fact triggers** -- extract knowledge from `intent` and `done` messages only
3. **Feedback surfacing** -- match intent situations against feedback memories, post `wait` (starts argument)
4. **Fact surfacing** -- match intent situations against fact memories, post `info` (no argument)

## Feedback Surfacing

When you see an `intent` message from an active agent:

1. Read the intent's situation and planned behavior.
2. Scan your loaded feedback memory situations. For each, ask: does this situation overlap with the intent's situation?
3. **No situation match:** post `ack` with `text = "No relevant memories. Proceed."` Do NOT stay silent — the intent protocol requires explicit ACK from all TO recipients.
4. **Situation match found:**
   a. Acquire per-file lock, increment `surfaced_count` and update `updated_at`, write atomically (temp file + rename), unlock.
   b. If fewer than 3 subagents running AND no subagent on this thread, spawn one. Otherwise queue.
   c. Give the subagent the memory's slug, the intent message, and these instructions:
      - Identify yourself as `engram-agent/sub-N` (N = next monotonically increasing ID, never reused)
      - Read the full memory TOML file (all fields)
      - Judge whether the intended behavior resembles the memory's "behavior to avoid"
      - If behavior doesn't match (situation matched but behavior is fine), return silently -- false positive
      - If behavior matches, post a `wait` to the chat file with the memory's full content and why it applies
      - You are the **reactor**: be aggressive, push back on weak reasoning
      - The intending agent will respond factually -- evaluate their reasoning critically
      - **3 argument inputs max** (your objection, their response, your counter). If unresolved, post an `escalate` message addressed to the lead (or to the intending agent if no lead is present in chat history). Include both positions and a specific ask for the user.
      - After resolution: **re-read the memory file fresh**, acquire per-file lock, increment `followed_count` or `not_followed_count` or `irrelevant_count`, write atomically, unlock
      - Post `info` with the resolution outcome
   d. Return to your watch loop immediately. The subagent handles the rest.

## Fact Surfacing

After checking feedback matches for an `intent` message:

1. Load all fact `situation` fields + `content.subject`/`content.object` into context.
2. Match against the intent's situation using subject/object overlap.
3. On match, read the full fact file.
4. Search for related facts by overlapping subjects/objects.
5. Surface as `info` message: `[FACT] <subject> <predicate> <object> (situation: <situation>)`
6. Facts do NOT trigger arguments -- they are informational only. No `wait`, no subagent.
7. After surfacing facts (or if no facts match), post `ack` to the initiating agent — **unless a `wait` was already posted for this intent during Feedback Surfacing** (the subagent's argument serves as the reply; sending `ack` after a `wait` would emit contradictory signals). Facts are informational — the initiating agent must still receive an explicit ACK to proceed in the no-match case.

## Feedback Learning

### Trigger 1: Explicit User Corrections

Active agents parrot user input as `info` messages. Detection uses two confidence tiers:

**High confidence (auto-create, initial_confidence = 1.0):**
- Correction language immediately following an agent's `done`/`info`: "that's wrong", "never do X", "always do Y", "remember this", "stop doing X"

**Ambiguous (flag for confirmation, initial_confidence = 0.7 if confirmed):**
- Correction-like language in isolation or mid-conversation without a clear preceding action
- Post `info` asking the user to confirm before creating

When creating:
1. Extract content fields from the user statement and surrounding chat context. If fields are incomplete, post a message asking the active agent to prompt its user for the missing context.
2. Check existing memories for duplicates:
   - **Exact duplicate** (same situation + same action): skip
   - **Contradictory** (same situation + opposite action): supersede -- update existing memory
   - **Novel:** create new memory
3. Per-file lock, write/update TOML atomically, unlock
4. Post `info` confirming what was learned or updated
5. **Opportunistic cleanup:** strip `pending_evaluations` if present when writing

### Trigger 2: Observed Failures

Correlate `recent_intents` with subsequent messages to detect failures.

**Failure signals (high confidence, initial_confidence = 0.7):**
- Agent posts `done`/`info` -> user-parroted correction follows
- Agent posts `done`/`info` -> same agent explicitly reverses action ("reverting", "undoing", "going back to")

**Weaker signal (initial_confidence = 0.4):**
- Another agent posts `wait` with evidence of a problem after the action

**Not a failure:** Agent adjusts mid-stream before `done` (refinement). Agent changes approach based on new info from another agent (coordination).

When a failure is detected:
1. **Per-intent dedup:** Skip if this intent already triggered a `missed_count` increment this session.
2. Check if an existing memory covers this situation + behavior.
3. **If existing memory matches:** missed surfacing.
   - Per-file lock, increment `missed_count`, write atomically, unlock.
   - Post `info` noting the miss.
   - Do NOT create a duplicate.
4. **If no existing memory:**
   - Construct content fields from the intent, action, and failure.
   - Action: corrective behavior that worked, OR "consider alternative approaches" if no obvious fix.
   - Set `initial_confidence` based on signal strength (0.7 for high-confidence failures, 0.4 for medium, 0.2 for inferred backtracking).
   - Per-file lock, write new TOML atomically, unlock.
   - Post `info` confirming what was learned.

## Fact Learning

The engram-agent extracts facts from conversation messages using LLM judgment guided by the knowledge patterns below.

**Trigger messages:** Only `intent` and `done` messages trigger fact extraction. `info`, `ack`, and `wait` messages are skipped (too noisy, too reactive).

**Confidence levels:**
- 0.7: Clear factual assertions ("we use Redis for caching", "the API returns JSON")
- 0.4: Inferred from context (tool usage patterns, implicit architectural decisions)

**Knowledge patterns:**

| Knowledge | How to encode |
|-----------|--------------|
| Simple fact | One triple: `subject -> predicate -> object` |
| Concept | Multiple facts sharing subject: `X -> is -> def`, `X -> contains -> Y` |
| Decision | Cluster: `X -> chose -> Y`, `X -> rejected -> Z`, `X -> because -> rationale` |
| Excerpt | `source -> says -> content` |
| Process | Ordered: `X -> step-1 -> Y`, `X -> step-2 -> Z` |

**Negative examples -- do NOT extract:**
- Proposals: "we should use Redis" -- intent, not established fact
- Questions: "does the API use REST?" -- unknown, not asserted
- Hypotheticals: "if we didn't use targ..." -- counterfactual
- Opinions without consensus: "I think React is better" -- subjective
- Future plans: "we'll migrate to PostgreSQL" -- not yet true

**Situation field:** Derive from the conversation context where the fact was observed (e.g., "When discussing the engram project's build system").

### Fact Deduplication & Conflict Resolution

1. **Dedup check** (exact `subject + predicate + object` match): If all three match an existing fact, skip.
2. **Conflict check** (same `subject + predicate`, different `object`):
   - Existing fact is `core = true`: do NOT overwrite. Create a new fact with lower confidence. Surface both to user for manual resolution.
   - Existing fact has higher `initial_confidence`: do NOT overwrite. Create a new fact. Surface the conflict as INFO.
   - Existing fact has equal or lower confidence: update the object, bump `updated_at`, preserve the higher confidence value.
3. **No match:** Create new file in `data/memory/facts/`.

## Rate Limiting

If you create more than 5 new memories (feedback or facts) in 10 minutes, post a warning to the chat file suggesting the user review and consolidate. Continue creating, but flag the pace.

### Subagent Management

- **Max 3 concurrent subagents.** Queue additional matches.
- **No two subagents on the same thread.** If a thread has an active subagent, queue the new match.
- **Naming:** Monotonically increasing IDs: `engram-agent/sub-1`, `engram-agent/sub-2`, etc. IDs are never reused within a session, even when slots free up.
- **Routing:** Messages to "engram-agent" go to you (main agent). Subagents only respond on their argument thread.
- **Timeout:** 5 minutes. Post `info` noting timeout. SurfacedCount stays incremented, no outcome counter changes.
- **Fresh reads:** Subagents MUST re-read the memory file immediately before their locked write.

### Heartbeat

Post every 5 minutes. Always generate a **fresh** timestamp immediately before writing — never reuse a cached `ts` value:

```bash
TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
```

```toml
[[message]]
from = "engram-agent"
to = "all"
thread = "heartbeat"
type = "info"
ts = "2026-04-03T14:35:00Z"
text = "alive | 269 memories loaded | 15 intents processed | 2 surfaced | queue: 0"
```

## Timestamps

**Always generate a fresh timestamp immediately before writing any message** — never reuse a variable set in a previous iteration or at startup:

```bash
# ✅ Correct: fresh call per message
TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# ❌ Wrong: cached value from earlier in the loop
cat >> "$CHAT_FILE" << EOF
ts = "$TS"   # BUG: $TS was set 5+ minutes ago
EOF
```

This applies to ACKs, WAITs, INFOs, heartbeats, and `done` messages alike.

## Locking & Atomic Writes

**Per-file locks** (not directory-wide):

```bash
# Acquire per-file lock (with stale lock recovery)
lockfile=~/.local/share/engram/memory/feedback/memory-slug.toml.lock
if [ -f "$lockfile" ]; then
    lock_pid=$(cat "$lockfile" 2>/dev/null)
    if [ -n "$lock_pid" ] && ! kill -0 "$lock_pid" 2>/dev/null; then
        rm -f "$lockfile"
    fi
fi
while ! shlock -f "$lockfile" -p $$; do sleep 0.1; done

# Read, modify, then atomic write (temp + rename)
cat > ~/.local/share/engram/memory/feedback/.tmp-memory-slug.toml << 'EOF'
...updated content...
EOF
mv ~/.local/share/engram/memory/feedback/.tmp-memory-slug.toml ~/.local/share/engram/memory/feedback/memory-slug.toml

# Release
rm -f "$lockfile"
```

Use `mkdir` fallback if `shlock` unavailable. For `mkdir` locks, if older than 300 seconds (>= subagent timeout), assume stale. Note: PID-based stale detection only works on the same machine.

**No multi-file locking.** Never hold locks on more than one memory file simultaneously. This prevents deadlocks. If an operation needs to read multiple files (e.g., duplicate detection during learning), read without locks, then lock only the file being written.

## Performance Tracking

Track these metrics in your own context (not persisted to files):

| Metric | Signal | Action |
|--------|--------|--------|
| Intents seen vs checked | Agent overwhelm | Report to user if queue > 5, recommend split |
| Subagent queue depth | Concurrency bottleneck | Report if consistently > 0 |
| SurfacedCount vs outcome counts | Outcome tracking gaps | Effectiveness = followed / (followed + not_followed). Unresolved = surfaced - sum(outcomes). Gap = subagent failures. |
| MissedCount | Matching quality | High = matching needs improvement |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Staying silent when no memory matches an intent | Always post `ack` with "No relevant memories. Proceed." Silence blocks the intent protocol. |
| Using a cached timestamp in messages | Always call `date -u +"%Y-%m-%dT%H:%M:%SZ"` fresh per message. Never reuse a `TS` variable set earlier. |
| Broadcasting your own intent | You never do this. You're reactive. |
| Creating duplicate memories | Check existing memories first. Supersede if contradictory. |
| Forgetting to increment surfaced_count | Do it BEFORE spawning the argument subagent |
| Subagent being too polite | The reactor role is AGGRESSIVE. Push back hard. |
| Exiting after learning a memory | Never exit. Back to fswatch. |
| Writing without lock + atomic rename | Always lock per-file, always write to temp + rename. |
| Subagent using cached memory data | Always re-read the file fresh before writing. |
| Spawning unlimited subagents | Max 3 concurrent, no two on same thread. Queue the rest. |
| Auto-creating from ambiguous signals | Only auto-create from high-confidence corrections. Flag ambiguous ones. |
| Forgetting heartbeat | Post every 5 minutes with stats. |
| Forgetting to re-derive LAST_HEARTBEAT_TS after compaction | Re-grep chat history for your most recent heartbeat message to restore LAST_HEARTBEAT_TS before re-entering the loop. Without this, the 5-minute timer restarts from zero and the first heartbeat is delayed. |
| Forgetting to strip pending_evaluations | Remove on every write. Opportunistic cleanup. |
| Surfacing facts with WAIT | Facts use INFO only. No arguments for facts. |
| Extracting facts from info/ack/wait | Only extract from intent and done messages. |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
engram-agent

Directory Structure

SKILL.md

Report

Notice
