Starting with “Triggered Every Five Minutes, Runs for Ten”

memU’s passive memorization is performed by each coding agent itself. A scheduled task for each host launches an agent session and runs the following pipeline:

1
prepare
2
  → slice new content from session logs
3
  → mirror Recall Files from the store
4
  → generate jobs
5

6
agent self-evolve
7
  → process jobs in order
8
  → modify memory / skill
9
  → describe resources touched during the run
10

11
commit
12
  → compare against the content-hash baseline
13
  → submit changes to the store
14
  → advance the cursor and clean up ephemeral run files

Agent self-evolution is the expensive part. It reads transcripts, makes judgments, and edits Markdown. It is not a script that finishes instantly.

That gives us a simple stress case: what happens if the scheduled task fires every five minutes while each run takes ten minutes?

Over time, close to half of the triggers will indeed do no work. More precisely, however, they are not blocked by a marker after entering prepare. They are skipped by the scheduling layer before a second bridging process starts:

• Windows Task Scheduler uses -MultipleInstances IgnoreNew. When the old instance is still running, the new trigger is ignored;
• the Unix cron wrapper acquires an atomic mkdir .bridge.lock. If the lock already exists, the new trigger records skipped: another bridging run is in progress and exits successfully.

This is therefore not a random 50 percent probability. It is a stable outcome produced by the relationship between run duration and trigger interval. If a run lasts slightly longer than ten minutes, the trigger at minute ten may also arrive before the previous run exits, so the execution ratio will no longer be exactly one in two.

This small example exposes a distinction that had remained blurred for a long time: what do the marker, lock, and manifest each protect?

Three Local States That Are Easy to Confuse

1
{ "started_at": 1788253200.0 }

1
~/.memu/hosts/<host>/
2
  sessions/
3
  jobs/
4
  memory/
5
  skill/
6
  resources.md
7
  .session_manifest.<host>.json
8
  .session_manifest.<host>.json.pending
9
  .memory_manifest.json
10
  .bridging_run.<host>.json
11
  .resource.tmp

1
Official bridging runs of the same host: mutually exclusive
2
Bridging runs of different hosts: may run concurrently
3
Manual prepare that bypasses the wrapper: outside scheduler protection

The Store, Working Mirrors, and Hash Baselines

Before understanding the concurrency model, we also need to identify where Recall Files actually live.

The authoritative state in memU is not any Markdown directory. It is the shared persistent store: usually a database in local mode and a remote service in Cloud mode. Every host reads the same ~/.memu/config.env, so memory learned from one host can be retrieved from another.

The local memory/ and skill/ directories are mutable working mirrors. Agents edit those Markdown files directly. The manifest is the content-hash baseline representing a particular point in time.

1
Shared store                        authoritative state
2
Local memory/ and skill/            mutable working mirrors
3
.memory_manifest.json              baseline from the last successful commit
4
.memorize_manifest.json            baseline for the active proactive run

1
Host A: store v1 → edit Profile → commit v2
2
Host B: store v1 → edit Profile → commit v3
3

4
Final state: v3

Proactive Memorization Does Not Need All of the Host Complexity

Passive bridging and proactive memorization accept different kinds of input.

Host bridging must handle long-lived session logs, incremental cursors, self-session recognition, recurring schedules, and crash leftovers. Proactive memorization receives one explicit conversation from a developer and hands prepared jobs to the current agent. It does not need to inherit the host pipeline’s entire lifecycle.

A developer workspace can currently be described as:

1
<workspace>/
2
  input/
3
  jobs/
4
  memory/
5
  skill/
6
  .memorize_manifest.json
7
  .memorize_run.json
8
  .resource.tmp
9
  resources.md

.memorize_run.json has a different meaning from the bridging marker. It means that one proactive memorization run is still unfinished in this workspace:

• prepare rejects a new run when an active one exists;
• commit requires an active run;
• a successful commit removes the marker and ephemeral files;
• a failed commit preserves the state for retry.

That protects the sequential lifecycle of one shared developer workspace, but it also turns all proactive memorization into one global gate. Once proactive memory creation becomes frequent, inputs arriving concurrently from different hosts or sessions run into the same queue.

Target Layout: Every Memorization Is an Independent Run

The right design is not to remove all protection from a shared workspace. It is to reduce the isolation unit from a host to a run:

1
~/.memu/developer/
2
  runs/
3
    <run-id-a>/
4
      input/
5
      jobs/
6
      memory/
7
      skill/
8
      .memorize_manifest.json
9
      .memorize_run.json
10
      .resource.tmp
11
      resources.md
12
    <run-id-b>/
13
      ...

~/.memu/developer becomes only a namespace for runs. Each memu memorize prepare atomically creates a unique <run-id>, then returns the run ID, worktree path, executor prompt, and matching commit command. The agent, verify-resources, and commit all bind explicitly to that run afterward.

This gives us a clear concurrency boundary:

1
Host scheduled task: remains single-instance
2
memorize prepare: may create different runs concurrently
3
One run: remains single-owner / single-lifecycle
4
Shared store: accepts concurrent commits; conflicts are last-writer-wins by (track, name)

Why Not Introduce a Central Worker Yet?

From a consistency perspective, the most comfortable design is a central worker: enqueue every memorization request, let one finish and refresh the latest state, then start the next. Every task would branch from the newest snapshot, and same-key concurrent replacement could disappear entirely.

But this changes far more than the location of the queue.

Coding-agent self-evolution uses each host’s own agent and token. A central memU server that runs its own LLM service contradicts the goal of letting the agent perform the work with its existing capabilities. Turning it into an MCP server that only coordinates retrieval and memorization introduces a persistent process, connection availability, sandbox access, host configuration, and lifecycle management.

It would also widen the gap between the open-source local edition and a cloud service. Where the coordinator lives, who keeps it online, and how restricted sandboxes such as Codex connect to it all become new system problems—not merely solutions to commit ordering.

CLI plus per-run worktrees preserves agent-owned self-evolution without adding permanent infrastructure. It accepts store-level last-writer-wins in exchange for a much smaller deployment and architectural cost.

This is not the strongest consistency model imaginable. It is the friendlier engineering choice under the current constraints.

Codex Already Uses the Unified Host Layout

Codex once retained ~/.memu as its runtime worktree for compatibility, but it has since moved to:

1
~/.memu/hosts/codex/

The current Codex HostSpec does not override base_dir, so it uses the same ~/.memu/hosts/<host> default as every other host. Its jobs, sessions, memory, skill, manifests, and resources all live in that runtime directory.

It is also important to distinguish source layout from user state:

• src/memu/hosts/codex is the source package for the Codex adapter;
• ~/.memu/hosts/codex is the Codex bridging worktree on the user’s machine.

They share a name, but one organizes code and the other stores runtime state.

Root Memory Is a Shared Retrieval Cache

Even after Codex moved, the root still contains:

1
~/.memu/memory/
2
~/.memu/skill/

These are neither a host’s evolve worktree nor a complete Markdown snapshot of the database. They are a shared read-through cache materialized lazily from retrieval hits.

When retrieve receives a matching Recall File from the store, it atomically writes the complete body to ~/.memu/<track>/<name>.md, then returns an openable path to the agent. Every host can therefore read results through a stable location, and a deleted cache file heals the next time it is retrieved.

“Read-only” here is an ownership contract rather than an operating-system permission:

1
The store is the only authoritative write target
2
Host / run mirrors may be edited by agents and written back through commit
3
The root retrieval mirror is refreshed only by memU; agents read it and cannot commit from it

The root mirror should not be described as a complete materialized database view. A file that has never been retrieved may never appear on disk, while an object removed from the store may leave stale cache behind because no full sweep or deletion reconciliation runs here.

A complete, enumerable, version-consistent read-only view would need a dedicated producer: paginate through the entire store, generate every file in a temporary directory, reconcile removals, then publish through a directory version or index switch. That reintroduces questions about refresh frequency, failure recovery, and producer ownership.

The existing read-through cache already satisfies the agent’s need to open retrieved results. If the path makes it look too much like authoritative memory, it could eventually move to ~/.memu/cache/recall-files/<track>. That would improve naming and ownership clarity, but it is not required by the concurrency model.

Final Architecture Decision

After tracing the whole path again, the final boundary is simpler than my initial mental model:

1. Keep host bridging single-instance. It protects a long-lived shared worktree with cursors, jobs, and crash recovery;
2. Keep worktrees isolated by host. Different hosts may evolve concurrently while sharing one authoritative store;
3. Isolate proactive memorization by run. ~/.memu/developer manages runs/<run-id>, and sibling runs remain independent;
4. Let each marker manage only its own lifecycle. The bridging marker measures a cycle; the memorize marker records one run’s active or completed state;
5. Retain (track, name) last-writer-wins for shared conflicts. Per-run isolation provides local filesystem safety, not transactional merging;
6. Keep root Recall Files as a memU-owned shared retrieval cache. Agents may read it, while only host or run worktrees can affect the store through commit;
7. Keep the CLI rather than adding a persistent central worker. This preserves complete multi-agent, multi-host, and open-source local deployment without a new infrastructure layer.

The important change is not merely adding a runs/ directory. It is assigning three concurrency problems to the layers that actually own them:

1
The scheduler prevents duplicate runs of one host
2
Filesystem isolation prevents local competition between runs
3
The store's identity key determines the outcome of concurrent commits

Once those three layers are no longer confused, proactive memorization does not need to overturn existing bridging. It only needs to draw the boundary again at a more appropriate granularity.