How Eney Handles Memory

TL;DR: Eney Harness implements durable memory as per-working-directory Markdown files. The harness always injects the MEMORY.md index at session start; the model decides whether to save, update, delete, or read a more detailed topic file.

It is not a vector database, semantic retriever, or autonomous memory-writing pipeline. The installed app can therefore behave like user-level memory when every chat starts in the same home-directory working path. In-session context compaction is separate: it deterministically trims history; it does not generate an LLM-written recap.

Provenance: this basic design is inherited from HKUDS OpenHarness. Eney Harness is a Swift port with MacPaw-specific app, permission, and evaluation integration.

1. Scope

The memory namespace is derived from the current working directory (cwd): the project name plus a hash of its canonical path. With the current app starting in /Users/akhilesh.gotmare, chats share one home-directory memory namespace unless the app changes cwd to a specific project folder.

Working directory/Users/akhilesh.gotmare

Derived memory folder~/.eneyharness/memory/akhilesh.gotmare-<path-hash>/

Durable filesMEMORY.md plus topic Markdown files.

2. What The Harness Does Automatically

Session startsThe harness resolves the current cwd.

Load indexRead up to 200 lines from MEMORY.md.

Build system promptInclude the memory directory, operating instructions, and index text.

Model turnThe model sees the index before responding.

Automatically present: the memory directory path and the MEMORY.md contents.
Not automatically present: full contents of every topic file.
Not automatic: semantic search, ranking, deduplication, retention policy, summarization, or writes.

3. What The Model Decides

The model receives normal tool definitions, not a hard-coded memory policy. Their descriptions say to use durable memory for user preferences, project facts, and context that should survive future sessions. Saving and updating are write operations and pass through Eney's permission system.

Model action	Tool or mechanism	Harness responsibility
Save a durable fact	`MemorySave` writes `<topic>.md` with YAML frontmatter and Markdown body.	Validates the path, checks permissions, writes the file.
Make it discoverable later	`MemoryUpdateMemoryMd` replaces the index with concise pointers.	Checks permissions and writes `MEMORY.md`.
Use a remembered topic	The injected index is often sufficient; otherwise the model uses normal file-reading tools on the named topic file.	Injects the index at the next session start; it does not retrieve a topic automatically.
Remove obsolete memory	`MemoryDelete` removes a topic file; the model should also update the index.	Prevents deleting the reserved `MEMORY.md` file and checks permissions.

Decision boundary: a transient event such as a one-off failed test should ideally not be saved, while a stable preference such as “use concise imperative commit messages” should. The checked-out Harness does not enforce this distinction; model behavior and prompting determine it.

4. Example Trajectories

Write: a durable preference

SYSTEM # Memory ## MEMORY.md (not created yet) USER "Please always keep my commit messages concise and imperative." MODEL MemorySave({ name: "user_preferences", type: "user", description: "Commit-message preference", content: "Use concise, imperative commit messages." }) HARNESS permission check -> write user_preferences.md MODEL MemoryUpdateMemoryMd({ content: "# Memory index\n- user_preferences.md: Commit-message preference" }) HARNESS permission check -> write MEMORY.md MODEL "Got it."

Later session: use the preference

SYSTEM # Memory ## MEMORY.md - user_preferences.md: Commit-message preference USER "Commit these changes." MODEL Read(".../user_preferences.md") # optional; index may be enough MODEL Git commit with a concise, imperative message

Key point: the harness deterministically supplies the index; the model makes the discretionary choices to write, read a topic, and apply a remembered fact.

5. Within-Session Context Compaction

Before every model request in the agent loop, the harness estimates the system prompt plus conversation size. It compacts at 75% of the configured context window by default; the later 90% and 95% thresholds select progressively more destructive tiers. Claude-family model names default to a 200k-token window; other models default to 128k unless the host supplies an override.

Pressure	What Eney keeps	What it inserts or removes
Tier 1 75% to <90%	All messages and all tool calls.	Truncates only the single largest tool result to roughly 40%, retaining its beginning and end.
Tier 2 90% to <95%	The six most recent conversation messages.	Removes older messages and prepends a harness-authored note such as `[earlier conversation: 18 message(s) elided due to context pressure]`.
Tier 3 95%+	History from the latest substantive user message onward.	Removes earlier messages; replaces images and tool results with explicit “elided” placeholders.

BEFORE NEXT MODEL CALL [many earlier messages and tool outputs] USER "Now update the report." ASSISTANT ToolUse(Read, ...) TOOL (large file result) TIER 2 AFTER COMPACTION <agent-note kind="compaction_summary"> [earlier conversation: 18 message(s) elided due to context pressure] </agent-note> USER "Now update the report." ASSISTANT ToolUse(Read, ...) TOOL (large file result) NEXT MODEL CALL The model receives that compacted transcript. It can see that earlier history existed, but it cannot recover its substance from this note.

Answer: yes, the compacted transcript is retained for subsequent turns in the same session (and is eligible for normal session persistence). But no, this checkout does not maintain a semantic, model-written session summary. The so-called compaction_summary is a small deterministic elision marker, not a recap of goals, decisions, or facts. A host could add out-of-band summarization through replaceMessages(...), but Eney Harness does not do so itself.

6. Production Memory vs. Evaluation Memory

Aspect	Installed Eney / Harness	Eney Evaluation Platform
Storage	Persistent per-`cwd` filesystem directory.	Fresh temporary per-task directory.
Initial state	Existing `MEMORY.md` and topic files.	Task-specific memory fixtures seeded by the evaluator.
Persistence	Survives later sessions using the same `cwd`.	Removed after the task completes.
What an eval proves	Not applicable.	Whether the agent reasons correctly with supplied memory, not retrieval quality or long-term retention.

7. Comparative Research: Eney And Seven Open-Source Harnesses

Snapshot cloned and inspected on July 20, 2026. The comparison separates personal-agent designs from developer-oriented controls: the question is not whether Eney should copy a whole framework, but which memory-product choices fit a persistent Mac assistant. The final column concerns only the live, multi-turn transcript, not durable user memory.

Harness	GitHub stars July 20, 2026	Durable-memory design	Within-session multi-turn compaction	What it suggests for Eney
Eney Harness MacPaw Swift port	Private	Per-`cwd` Markdown topic files plus a prompt-injected `MEMORY.md` index; the model decides writes and reads.	Deterministic only. At 75/90/95% pressure it truncates one large tool result, then elides old messages, then keeps only the latest user-led slice. Later turns receive an elision marker, not a semantic summary.	Cheap and predictable, but it loses the substance of evicted work. A structured checkpoint is the clearest quality gap.
OpenHarness Developer-oriented base	15.0k	Per-`cwd` Markdown topic files plus a prompt-injected `MEMORY.md` index; model decides writes and reads.	Hybrid. Micro-compacts oversized tool outputs, then makes an LLM summary of older history while retaining recent messages; it also persists a bounded per-session Markdown checkpoint.	The public upstream has moved beyond Eney’s current compactor. Reuse its checkpoint contract without coupling user memory to `cwd`.
OpenClaw Personal-agent reference	383.6k	Compact `MEMORY.md`, daily notes, hybrid keyword/vector `memory_search`, pre-compaction memory flush, and optional reviewable “dreaming” promotion.	LLM checkpoint. Before usable context is exhausted, it summarizes old history, retains roughly 20k recent tokens, and carries forward file-operation details.	Strongest layered-memory reference: always-on facts remain small while detailed history is retrieved on demand.
Hermes Agent Personal-agent reference	217.8k	Separate bounded `MEMORY.md` and `USER.md`, FTS5 search over past sessions, proactive writes, and optional external semantic-memory providers.	Two-layer LLM compaction. Prunes old tool output, then writes a structured checkpoint while retaining protected head and tail context; primary trigger is 50%, with an 85% gateway safety net. It rotates to a linked child session.	Separate user profile from agent/project knowledge; offer an on-demand “did we discuss this?” recall path.
Nanobot Personal-agent reference	45.9k	`SOUL.md`, `USER.md`, and project memory; compressed JSONL history; a scheduled “Dream” consolidation pass; Git-backed review and restore.	LLM archival summary. When its replay window or token budget requires it, it archives evicted history to `history.jsonl`, keeps a live tail, and injects the latest summary into later prompts; a raw archive is the fallback.	Useful model for slow, auditable consolidation rather than asking the foreground model to curate everything perfectly.
PicoClaw Lightweight personal agent	29.7k	Long-term `MEMORY.md` plus the most recent three daily-note files injected into the prompt.	Hierarchical LLM summaries. Its newer Seahorse path performs leaf compaction every turn, can condense prior summaries, and retries aggressive compaction after an overflow; its legacy path uses configurable message/token thresholds.	A low-complexity intermediate step: preserve recent context without treating every detail as permanent memory.
Gemini CLI Developer-oriented, useful pattern	106.1k	An experimental background job mines idle transcripts and proposes reviewable memory/skill patches; it never applies them automatically.	Verified LLM state snapshot. At 50% context by default it preserves the newest 30%, summarizes earlier history, then makes a second LLM pass to check the summary; older tool results are truncated to a fixed budget first.	Good safety model for automatic learning: candidates, user review, atomic apply, and no silent mutation.
OpenCode Developer-oriented control	187.9k	Durable sessions and summaries, but no comparable user-memory/retrieval layer was found in the inspected source snapshot.	LLM checkpoint plus pruning. On overflow it prunes older tool results, summarizes the older turns into a persisted compaction entry, and keeps a recent tail selected by token budget.	Shows that session persistence alone is not a personal-memory product.

Important distinction: Eney’s current checked-out Swift implementation is not simply the current public OpenHarness compactor in another language. Upstream now has LLM-written checkpoint summaries; Eney’s Compactor.swift deliberately performs deterministic truncation and elision instead. That explains why Eney can compact without another model call, but cannot preserve a semantic handoff of the discarded turns.

Where Eney sits

EneySmall file index in prompt; model-managed writes; deterministic transcript elision.

OpenHarness / Gemini / HermesStructured LLM checkpoint plus a protected recent tail.

OpenClaw / Nanobot / PicoClawSession summaries paired with explicit durable-memory layers and/or controlled consolidation.

Conclusion: retain Eney's lightweight tool loop and permission model, but move its memory product toward the personal-agent pattern: stable user memory, optional workspace memory, compact prompt context, and a retrievable long tail.

8. Practical Implications

Simple and inspectable: a user can read, edit, or remove memory as ordinary Markdown files.
Prompt-budget risk: the full index is injected on every new session, subject only to a 200-line cap.
Model-quality dependency: a weaker model may fail to save useful facts, maintain the index, or open the relevant topic file.
Recommended direction: always inject a small user profile; add project/workspace context only when relevant; retain detailed notes/history outside the prompt; retrieve it with lexical or hybrid search; consolidate only through a reviewable background workflow.
Different from Mnemos: no observed embedding, retrieval ranking, cross-session consolidation, or learned memory policy is wired into this Harness checkout.

9. Source Notes

This report is based on the checked-out MacPaw/eney-harness implementation: MemoryStore.swift, MemoryTools.swift, Paths.swift, system-prompt construction, Compactor.swift, and QueryEngine.swift. The evaluation distinction comes from the Eney Evaluation Platform's context-and-memory fixture ADR. Comparative source snapshots were cloned under Documents/Codex/2026-07-14/as/work/harness-memory-study on July 20, 2026; linked repositories and their memory documentation are the primary references.