evermind-ai-agent-memory

The token-saving switch for AI agents. Kills long-context anxiety — start a new chat anytime, tasks pick up seamlessly, nothing breaks. Chat goes to zero. Progress is fully kept. Your token bill roughly halves — every cent goes to real work. Two small extras: context gauge — see your real context usage at a glance; caring new-chat nudges — auto-alert when context runs long, auto-suggest when a task wraps up. New in 0.4: rule memory — the do's and don'ts you told your agent are restated every session, and enforced wherever your platform supports action hooks; one-line handover — say "handover" at a task break and the next session picks up exactly there. Save tokens. Save money. Save worry. Measured: a full recovery costs ~44K tokens; with Evermind it's ~12K — ~70% less, with zero progress lost.

Evermind

Progressive memory recovery for AI agents: your assistant stops losing context between sessions, without re-reading everything every time. Evermind first discovers where your memory actually lives (your files, your layout), then hands the agent a shift handover at session start.

Every new session feels like "day one at work"? This skill makes the agent read what matters (identity, rules, todos, latest work log), check an auto-generated change index before re-reading secondary files, and defer everything else until actually needed.

Platform support

Platform	How to use
Hermes (Nous Research)	Drop this folder into the agent's skills/ directory. On each new session say "recover memory" (or wire the SKILL.md procedure into a session-reset hook). Hermes injects SOUL/MEMORY/USER automatically — the skill detects host-injected identity and skips duplicate reads (the 55-75% cumulative savings case).
ClawHub / OpenClaw	Frontmatter is dual-compatible (standard fields + metadata.hermes). Install via clawhub install evermind-ai-agent-memory or copy into the agent's skills dir.
Claude Code / Cursor / Codex / other SKILL.md agents	Copy this folder into the project or agent skills directory; at the start of a session, instruct the agent to follow SKILL.md (the procedure is model-agnostic).
Any LLM, any OS	Recovery logic is pure convention + one Python stdlib script — model-agnostic, runs on Windows/macOS/Linux, no GPU.

What it gives you

• 🧠 No more lost context: identity, rules, todos always loaded — nothing important silently dropped; new sessions resume where you left off
• 📏 Rules remembered: the do's and don'ts you told your agent are re-stated at every recovery — and (where your platform supports hooks) enforced at action time. "It keeps forgetting I told it not to…" — that ends here
• 🔁 One-line handover: say "handover" at any task break; the next session starts exactly where you stopped
• ⚡ Fast + cheap: recovery cost ~44K → ~12K tokens (~70% less); with host-injected identity skipped, ~55-75% cumulative (measured 2026-09-04)
• 🔒 100% local: pure local scripts, zero API cost, nothing leaves your machine
• 📊 Context health: see your real context usage and get nudged as you approach the 30/50/70% lines (and well before a session bloats)

How it works

Layer	Reads	When	Cost
L3 Must-read	identity / rules / todos / latest journal	Every new session — the reliability anchor	small, fixed
L2 Conditional	other tracked files	Only if the change index flags a change; otherwise just the index summary line	≈0 ← savings live here
L1 On-demand	detail docs / history	Only when actually needed	0

The engine is scripts/memory_index.py: it discovers your memory files (role → real file), then hashes every L2-tracked file and flags only what changed (md5 + 24h window). No index → you either re-read everything (expensive) or gamble (risky). With the index you get neither.

Setup (≈30 seconds)

bash

# 1. get the skill (already done if you installed from ClawHub)
git clone https://github.com/ccy123abcd/evermind-ai-agent-memory.git
cp -r evermind-ai-agent-memory ~/.claude/skills/evermind   # or your agent's skills dir

# 2. cold start: no config needed — discovery finds your memory layout
cd evermind-ai-agent-memory
python scripts/memory_index.py --list .    # preview what discovery finds (nothing written)
python scripts/memory_index.py             # cold start: discover + write index

# 3. (optional) tune: copy config.example.yaml → config.yaml, set mode/roles/extras
#    or edit .evermind/discovery.json to override a discovered role

# 4. self-test
python scripts/memory_index.py --demo

Discovered roles are cached in .evermind/discovery.json — the agent reads it at recovery instead of re-scanning every session. Delete that file (or any discovered source) and it re-discovers automatically.

Usage (start of every new session)

1. Step 0 — Discover (first time or when sources moved): run python scripts/memory_index.py --discover . — it locates your memory carriers by common conventions (candidate list lives in the script header constants) and writes .evermind/discovery.json. Python unavailable? Fall back to the hand-list below (derived from the script; the script is authoritative). At every recovery, first stat the stored paths — any missing/unreadable source triggers re-discovery (never reuse stale paths).
2. Read the L3 must-read files: roles resolved in step 0/1 (rules, identity, todos, journal) + must_read_extra. Every one, no shortcuts. Host injected identity (Hermes/OpenClaw)? Mark identity ✅ (host) and skip the file probe. 2b. Rules alignment: from the rules file(s) just read, extract every imperative rule the user stated (do X / never do Y). List them explicitly in your recovery report — this is the moment the user experiences as "it remembered what I told it". Then write/refresh .evermind/rules.json (id, text, keywords per rule) so the guardrail can enforce them at action time (see Rules & guardrails). If the rules file is empty or has no imperative rules, say "no hard rules found" honestly.
3. Read the change index memory_index.md:
   • ✅ new change → read that file in full
   • ⏸ unchanged → read only its index summary line ← savings live here
4. L1 on-demand: consult detail docs only when a task actually needs them.
5. Context gauge: report real context usage — query your platform (Hermes /status; Claude Code /context; others: see the platform table below). Never invent a percentage; if the platform exposes none, say so. Optionally append context: N% to your recovery report.
6. Check for a handover note: if .evermind/handover.md exists, read it first (it is the fast pointer to where the last session stopped), then delete it — a handover is a one-shot note; keeping it would make the third session read a stale pointer. Authority stays with todos/journal — the handover only accelerates.
7. Report recovery honestly: identity ✅ (host) · rules ✅ CLAUDE.md · todos ✅ docs/TODO.md · journal ✅ journal/2026-09-04.md · rules aligned: 3 (r1 never delete without asking · r2 reply in Chinese · r3 …). If a role came up empty, list it explicitly — never claim a full recovery that didn't happen.

Context threshold nudges

Check context usage every time you see it (at recovery, and after every user turn when your platform exposes a gauge) — usage is a snapshot that jumps between turns: this turn may read 29%, the next 49%. Never assume the last reading still holds, and never wait for a threshold to be crossed before speaking up. Nudge when you are approaching a threshold too — a jump can skip a band entirely.

Hard rule — the nudge is the ready signal. Before ANY nudge goes out — pre-nudge or full nudge — refresh .evermind/handover.md with a one-line snapshot of where work stands (current task · what's done · what's next). The user may switch sessions the moment they read the nudge, and they must lose nothing. A nudge without a ready handover is not a nudge — it is a trap. If the user then says "handover" or switches, the handover is already there.

Usage	What to say (handover is refreshed first, always)
< 25%	healthy — nothing to say
25–30%	pre-nudge: "context is approaching the 30% line — I've noted where we are, so a switch stays safe and cheap"
30–45%	fine — keep working; a task boundary is still a fine moment to switch
45–50%	pre-nudge: "approaching 50% — I've noted where we are; plan to wrap up the current task at its boundary and switch"
50–65%	suggest: "task boundary reached? Good moment to switch to a fresh session — recovery is ~12K tokens, nothing is lost. Handover is ready."
65–70%	pre-nudge: "approaching 70% — I've noted where we are; wind down the current task, the next boundary should be a switch"
≥ 70%	recommend: "wrap up the current task and switch — this context is near its ceiling. Handover is ready."

Thresholds are tunable in spirit; the bands above are the defaults. The principle: never let a reading pass in silence just because it did not cross a line — and never nudge without a ready handover.

Switching is safe and cheap: that is the whole point of Evermind (recovery ≈ 12K tokens instead of tens of thousands of re-explaining).

Platform context queries

Platform	How to see context usage
Hermes	/status (usage %)
Claude Code	/context (window + usage — convert to %)
Cursor	composer status / model context indicator
OpenClaw	session/context indicator (varies by build)
unknown	report "this platform exposes no context gauge" — do not invent a number

Rules & guardrails

Evermind treats your rules as memory too — the most important kind. Two layers make them stick:

Alignment layer (every session). At recovery (step 2b) the agent restates the imperative rules it found in your rules files — do's and don'ts alike. You see, in plain text, that what you set is loaded. No rule file yet? Write your rules in CLAUDE.md/AGENTS.md/your rules file — plain sentences work: "Never delete files without asking." "Always reply in Chinese." "Ask before sending anything externally."

Enforcement layer (where the platform supports it). Prohibitions you never want broken ("never", "don't", "always ask first") get written to .evermind/rules.json (id / text / keywords), and a tiny local gate script checks every action before it runs:

bash

python scripts/rule_gate.py --check "delete the whole project folder"
# ⛔ blocked — violates rules you set: [r1] Never delete files without asking
# exit code 2 → the platform hook refuses the action

Claude Code — wire it with a PreToolUse hook (settings .claude/settings.json):

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command",
            "command": "python ~/.claude/skills/evermind/scripts/rule_gate.py" }
        ]
      }
    ]
  }
}

The gate reads the tool name + input from stdin, checks it against your rules, and exits 2 on a hit — Claude Code aborts the tool call. No hook support on your platform? The alignment layer still applies (the agent self-checks before actions) — but enforcement is only as hard as your platform allows.

The gate is pure stdlib, fails open (no rules file → pass), and writes nothing. It only ever blocks prohibitions (never / don't / always-ask-first) — positive rules ("always do X") are carried by the alignment layer, since an action gate cannot enforce them mechanically.

Handover protocol

Switching sessions is only free if the next session knows where the last one stopped. Say "handover" (or "交接/收尾") at any task break — a natural stopping point, a finished task, or when a context nudge suggests switching — and the agent writes .evermind/handover.md from the template (assets/handover-template.md): ✅ done (what matters next) · 📌 leftover (what's waiting, on whom) · 🔗 pointers (files/tasks that anchor it) · ➡️ next step. Each new handover overwrites the previous one; recovery reads it once and deletes it (step 6) — a consumed handover must never linger as a stale pointer.

The nudge bands above are the hard rule: any nudge — pre-nudge or full nudge — goes out only after .evermind/handover.md has been refreshed (see Context threshold nudges). A nudge without a ready handover is just anxiety, not a safe suggestion. Recovery reads the handover if present (step 6); authority always stays with todos/journal, the handover is the fast pointer.

Manual discovery fallback (Python unavailable)

Look for, in order (the script header candidate constants are authoritative — this is a summary):

• rules/identity: CLAUDE.md, AGENTS.md, .cursor/rules/ in the project; ~/.claude/CLAUDE.md in home (candidate constants in the script header are authoritative)
• todos: TODO.md / todo.md / todo.txt / tasks.md (root or docs/); ~/todo.txt or ~/.todo/ (todo.txt-cli)
• journal: newest YYYY-MM-DD.md/.txt under journal/, logs/, notes/, or docs/journal/
• profile: only if you configured one

Files

• scripts/memory_index.py — discovery + change-index generator (pure stdlib; --discover / --list / --demo / --mode internal|auto|manual)
• scripts/rule_gate.py — optional action-time guardrail (reads .evermind/rules.json; --check "desc" or PreToolUse stdin; --demo)
• assets/handover-template.md — handover note template
• config.example.yaml — configuration template (mode / roles / extras)
• Outputs: .evermind/discovery.json + memory_index.md + memory_index_state.json + (optional) .evermind/rules.json + .evermind/handover.md

Security

• Discovery scans candidate paths by name only (metadata, no content) and writes .evermind/discovery.json; the index reads and hashes only files you listed (roles + extras)
• Never writes your memory files themselves — its own outputs are limited to .evermind/discovery.json, the index md + state json, plus two optional files the agent maintains at your request: .evermind/rules.json (your extracted rules, for the optional gate) and .evermind/handover.md (your one-shot handover note, deleted after being read)
• Nothing is uploaded anywhere — fully local, no remote install pipelines, no script-to-shell execution
• Python standard library only. PyYAML optional: when absent, a built-in fallback parser reads the config (nested roles:, extras, flat role_* keys) — no silent config loss

Roadmap (managed edition)

• Auto user-profiling (preferences / habits)
• Cross-device sync + web console
• One-click deploy — don't want to self-configure? Managed edition = zero-setup, full system, continuous updates. → [Managed edition entry: TBD]

License

MIT-0 — free to use, modify, and sell.