Replies: 1 comment
|
Maintainer disclosure: I build Better Agent, a local workspace supervising native Claude, Codex, and Gemini sessions with durable event history and restart recovery. The report-first decision is the right first milestone. I would add four constraints before implementing capture: Capture completeness is a first-class resultA summary-only episode must state what was observed and what was unavailable. Useful fields:
If hooks are disabled or a provider schema changed, produce a degraded capture receipt. Do not silently fall back to a summary and later treat it as equivalent evidence. Provenance independence must be measurableTen episodes copied from one stale source are one line of evidence, not recurrence. Candidate consolidation should group evidence by independent origin: source revision/path, test execution, reviewer, provider session, and externally observed result. Store both supporting and contradicting episode IDs. Promotion needs a different authority from extractionThe same model may propose and rehearse a candidate, but canonical promotion should require current repository evidence plus an independent verifier role or deterministic gate. “Independent” should mean a distinct verification input/path, not merely another prompt in the same session. For project scope, a candidate should fail promotion when any load-bearing claim depends on absolute paths, user environment, secret-bearing configuration, or provider-specific behavior. Those belong in user-tooling memory even if they recur. Evaluate rejection quality, not only retained knowledgeThe POC should measure:
One important recovery invariant: live capture, capture while the UI is disconnected, and restart replay of the same provider events should create the same episode identity/content modulo timestamps. Otherwise dreaming can learn twice from one run or learn different facts depending on uptime. I would also keep generated rehearsal scenarios incapable of writing to the repository by construction. Their outputs are evaluation evidence, never authority to mutate canonical memory. License note: Better Agent is source-available and free for non-commercial use; commercial use requires separate permission. |
Uh oh!
There was an error while loading. Please reload this page.
Summary
Extend the existing
agent-ready-contextskill with an optional, evidence-grounded repository dreaming lifecycle.This proposal targets the stack introduced by the OpenWiki migration (#1): the staged OpenWiki lifecycle, the canonical
okf/wiki/OKF, and theINSTRUCTIONS.mdpreservation contract are its foundation.The lifecycle should allow any compatible coding agent or harness that assimilates Agent Smith’s skills to:
skill-creator;The preferred memory-formation engine should be LangMem, used through its storage-independent functional API and a small file-in/file-out adapter.
LangMem should be treated as a preferred, replaceable vendor engine—not as a mandatory Agent Smith runtime.
The architecture should remain:
This proposal must not turn Agent Smith into:
Agent Smith remains an automation and assimilation layer expressed as skills.
Product boundary: Agent Smith remains three skills
The entire distributable product remains:
References:
agent-ready-contextskill-creatorsubagent-profile-adapterTheir responsibilities should remain:
agent-ready-contextskill-creatorsubagent-profile-adapterRepository dreaming belongs inside
agent-ready-context.It is not a fourth action domain and must not become a separate distributable skill.
The other skills participate through their existing responsibilities:
subagent-profile-adaptergenerates the native capture and optional memory-curator projections for the active harness;skill-creatorreceives procedural candidates after consolidation and verification.Dreaming must never automatically modify:
okf/wiki/INSTRUCTIONS.mdcontract;Problems discovered in those assets may be reported for an explicit upstream change, but they must not be treated as learned project memory.
Relationship to issue #1 (resolved by the OpenWiki migration)
This issue builds on:
agent-ready-context’s staged, isolated lifecycle.Issue #1 determined which engine owns the canonical repository-memory OKF wiki. This issue determines how repository experience should be captured, consolidated, evaluated, and promoted through that engine.
The separation is:
INSTRUCTIONS.md)skill-creatorsubagent-profile-adapterThe current path is:
For reference, the legacy
v0.1.0path this replaced was:The engine-specific write operation changed with the migration. The capture, consolidation, evidence, rehearsal, privacy, and promotion policies proposed here are engine-portable and must remain so.
Memory taxonomy
Agent Smith should use the following explicit memory model.
Working memory
Working memory belongs to the current agent or harness.
Examples:
Lifetime: one task or session.
Agent Smith does not need to reproduce the harness’s context management.
Episodic memory
Episodic memory records a specific repository experience.
Examples:
An episode describes what happened in a particular context.
It is not itself an Agent Skill.
It may guide a future agent through retrieval as an analogous example, but it remains specific to an event and revision.
Semantic memory
Semantic memory contains durable facts, concepts, relationships, rationale, and repository understanding.
Its canonical representation is the repository’s LLM-wiki/OKF:
entered through
okf/wiki/index.md(deterministic inventory) andokf/wiki/quickstart.md(semantic front door), maintained by OpenWiki under the preservation contract inokf/wiki/INSTRUCTIONS.md.Semantic memory answers questions such as:
Procedural memory
Procedural memory contains reusable instructions that drive agent behavior.
Its canonical representation is:
Procedural memory answers:
skill-creatoris therefore not the episodic-memory store.It is the promotion and validation path from consolidated experience into procedural memory:
Orientation
AGENTS.mdremains the compact routing and operating surface.It must not become a memory log.
Dreaming may cause it to be refreshed only when:
Memory scope classification
Capture is inherently user-wide: transcripts, sessions, and episodes belong to one person’s work on one machine. Promotion is not. Every
MemoryCandidatetherefore carries an explicitscope, assigned during consolidation and re-verified before promotion:personaluser-toolingokf/wiki/tooling/overlay (local by default, stub committed)projectokf/wiki/(semantic) or.agents/skills/(procedural)Rules:
projectscope is a promotion precondition, not a hint. A candidate may be promoted canonically only when its evidence is reproducible from the repository alone — source paths, tests, configuration — with no dependence on one user’s machine, harness, credentials, or absolute paths. Environment-specific traces in the evidence forceuser-toolingorpersonal.user-toolingpromotion reuses the existing overlay rules: hand-authored pages underokf/wiki/tooling/, local by default, one outgoing link to project knowledge, never enumerated in committed indexes, never producer input. Dreaming may draft such a page; the link-policy validator gates it as usual.scope_rationaleis recorded on the candidate so the verifier and the human reviewer can challenge it.Current OpenWiki and Agent Smith baseline
The new lifecycle must extend the current implementation rather than replace it.
What the current stack already provides
agent-ready-contexton the OpenWiki stack already ships:scripts/run_openwiki_staged.py): dry-run corpus preview, filtered Git-tracked stage with no history and no remote, literal stockopenwiki code --init|--update --printargv, wrapper-owned deadline, and disabled-by-default telemetry;okf/wiki/INSTRUCTIONS.md, upstream-native location in the stage) with surgical-update and manual-edit-preservation rules;review.diffand a transactional, Markdown-only promotion intookf/wiki/;path@commit, a test command/result, or an external URL with access date; the next isolated update must preserve the edit (seereferences/openwiki-lifecycle.md, “Direct edits”);okf/external/) included in the staged corpus;okf/wiki/tooling/, gitignored except its committed stub).Reading the wiki needs no vendor CLI: the assimilating agent routes through
AGENTS.md → okf/wiki/index.md → quickstart.md → pages → source and tests.These capabilities are useful for:
What is missing (the gap this issue fills)
Dreaming should wrap and improve the existing direct-edit and staged-update lifecycles.
It must not create a parallel canonical promotion mechanism.
Legacy
v0.1.0OpenKB baseline (kept for reference)The pre-migration stack informed several requirements of this proposal and remains a useful reference point, even though it is no longer shipped.
OpenKB provided:
queryquery --savewiki/explorations/chat/savewiki/explorations/Reference: OpenKB
It was not sufficient as a complete episodic-memory system because:
The
v0.1.0skill also carried an evidence-backed findings lifecycle (okf/wiki/explorations/findings/→ promote/keep/drop → stagedopenkb add), a read-only semantic lint critic, and the optional OpenKB Skill Factory packaging path. Those exact mechanisms were retired with the migration, but their lessons carry over directly:skill-creatorgate).A saved answer — then and now — is a durable exploration, not automatically verified long-term memory.
Proposed architecture
Engine orchestration: OpenWiki and LangMem never invoke each other and share no state, credentials, or storage. They meet only at reviewed file boundaries: LangMem (behind the adapter) reads episodes plus read-only OKF excerpts and writes provisional candidates; Agent Smith governance turns verified candidates into
PromotionPackets; OpenWiki — or the deterministic direct-edit renderer operating under its preservation contract — is the only writer ofokf/wiki/, andskill-creatorthe only path into.agents/skills/. Episodes may cite wiki pages; the wiki never cites episodes. Either engine is replaceable without touching the other.LangMem’s role
LangMem should be the preferred implementation of the sleep engine because it already provides:
It is also ecosystem-adjacent: the pinned OpenWiki producer is itself a LangChain/LangGraph application, so the vendor family is already present in the toolchain — in a different runtime (Node) and behind the same replaceability rules.
Mapping LangMem’s memory types onto this stack
LangMem’s conceptual model distinguishes semantic, episodic, and procedural memory, formed either in the hot path or in the background. The mapping here is deliberate, and one part intentionally diverges:
okf/wiki/— a curated, typed collection; the orientation surfaces (AGENTS.md,INSTRUCTIONS.md) play the schema-bound profile roleRepositoryEpisodefiles underokf/.memory/— a superset (failures, reviewer corrections, revision binding, evidence ids), retrieved conservatively, never auto-injectedskill-creator; dreaming never rewrites harness instructions or the product skills, so LangMem’s prompt-optimization primitives are out of scope hereFormation timing: capture and triggers live in the hot path; consolidation does not. Capture hooks (harness lifecycle events, and optionally a consent-installed local git hook such as
post-commit) are cheap, deterministic, and may fire constantly during ordinary work — they write envelopes and episodes, never memory. The consolidation pass is “background” only in the sense that it never blocks the interaction loop and never writes canon mid-task. Since Agent Smith owns no daemon or scheduler, sleep passes necessarily run while the project is in use: at session end, at compaction, on explicit request while the harness agent is assimilating the OKF, or from a team’s own CI. A repository with no team automation still dreams — whenever an assimilating agent runs one bounded pass.Two operating regimes name this distinction: the waking dream (rêve éveillé) — the default: a bounded consolidation pass invoked during ordinary interactive use (session end, compaction, explicit request) by the same harness agent that is assimilating the OKF — and scheduled dreaming — the identical pass invoked by external automation (team CI, or an always-on gateway agent such as an OpenClaw deployment). Only the invoker differs; the pass, its gates, and its outputs are the same.
Agent Smith should use the storage-independent core rather than its agent-managed memory tools or persistent LangGraph Store.
Preferred interface:
create_memory_manager(...)Verified against the LangMem reference documentation:
create_memory_manager(model, schemas=..., instructions=..., enable_inserts=True, enable_updates=True, enable_deletes=False)returns aRunnable[MemoryState, list[ExtractedMemory]]over input{"messages": [...], "existing": [...]}— exactly the file-in/file-out shape this proposal wraps. A persistent LangMem store is optional upstream and never used here; persistence stays in Agent Smith’s files.Installation discipline
LangMem is installed with the same strictness as every other pinned Python helper (the markitdown precedent): exact version pinned as a PEP 723 dependency of the one-shot helper script (
dependencies = ["langmem==X.Y.Z"]), integrity captured trust-on-first-use through the documentedpip download+ sha256 procedure and recorded in the target repository’sAGENTS.mdpin table, telemetry and network behavior audited at pin time, and resolved only with consent through the configured index. The consuming agent selects the version; no skill file carries a literal pin.What LangMem does not cover (Agent Smith governance)
Verified against its documentation, LangMem provides extraction, consolidation, search tooling, and prompt optimization — nothing else in this lifecycle. In particular it does not generate rehearsal or self-interrogation questions over the OKF, transcripts, or memory; does not evaluate retention, plasticity, transfer, or routing; does not classify scope; and does not verify evidence. All of that stays Agent Smith’s own machinery (
prepare_rehearsal.py, the verification phase, the evaluation suites). The rehearsal generator may use the same pinned model, but through Agent Smith’s schemas and scripts — self-questioning is a governance feature, not a LangMem feature.Why self-questioning matters for the sleep phase — the referenced research is explicit: Sleep-time Compute shows value comes from anticipating likely future questions before they arrive; Language Models Need Sleep makes rehearsal the mechanism that stabilizes new knowledge without eroding prior capability; Auto-Dreamer evaluates consolidation through future agent performance, which presupposes generated probes. A sleep pass that never interrogates its own output is just summarization.
Verified: LangMem does not do this. Its
ReflectionExecutor— the component whose name suggested it might — is confirmed by upstream's own tracker to be a deferred/background task-scheduling mechanism, not a self-questioning one: langchain-ai/langmem#11, "ReflectionExecutor: Future Cancellation Errors and Delayed Memory Updates" (open), describes async cancellation and timing bugs in delayed processing — nothing about generating probes or interrogating extracted memory. "Reflection" in LangMem's vocabulary means when consolidation runs, not whether it checks itself. The gap this issue identified is real and confirmed, not merely suspected.Two operational systems worth mimicking, found in comparable always-on assistants:
prepare_rehearsal.pyand the verification phase. It runs three cooperative phases on one schedule: light (reads recent short-term recall state, daily memory files, and redacted session transcripts; dedups and stages candidates; never writes toMEMORY.md), REM (builds theme and reflection summaries across recent traces, recording reinforcement signals; never writes toMEMORY.mdeither — this is the closest analogue to a self-questioning pass, surfacing patterns before any promotion decision), and deep (the only phase that writes: rehydrates snippets from live daily files to filter stale content, then ranks candidates against six weighted signals — Relevance 0.30, Frequency 0.24, Query diversity 0.15, Recency 0.15, Consolidation 0.10, Conceptual richness 0.06 — gated by threshold checks that must all pass:minScore,minRecallCount,minUniqueQueries). Disabled by default; phase summaries and diary entries are written toDREAMS.mdfor human review (docs.openclaw.ai/concepts/memory). The structural parallel to this proposal is direct: light ≈ Phase 2/3 (cheap episodic capture, bounded selection), REM ≈ the missing self-questioning step, deep ≈ Phase 6/7 (verification against weighted, gated criteria) — andDREAMS.mdis the same transparency instinct as ourreview.diff/MemoryReport. The multi-signal gate (never a single score) is directly adoptable forvalidate_memory_packet.py.Conclusion for implementation: ship the rehearsal/self-interrogation instruction ourselves — the gap is confirmed, not hypothetical — using OpenClaw's REM phase as the structural template (a distinct, non-writing pass between staging and promotion) and OpenClaw's deep-phase multi-signal gate as the template for
validate_memory_packet.py's threshold logic, with Hermes's tool-call-count trigger adapted as one input among the existing recurrence signals.Configuration and secrets resolution
LangMem is a library with no native config file and no dotenv loading of its own, so the consolidation helper owns resolution with plain dotenv semantics — no invented YAML, no bespoke parsing beyond
KEY=value— mirroring the OpenWiki precedent:okf/.langmem/is deliberately separate fromokf/.memory/: clean split between configuration/credentials and memory payload (both ignored; one new ignore rule each). Non-secret settings (model id, provider family, engine defaults) and secrets share the dotenv format since no built-in config format exists to mirror; the hands-off rules ofokf/.openwiki/apply identically — the helper script parses the file, the agent discusses locations and variable names only, never values.Conceptually:
LangMem should not:
Replaceability
The file interface must allow future use of:
The contract is owned by Agent Smith.
The transformation engine is replaceable.
Harness capture and enforcement
A skill cannot technically force every arbitrary harness to export its state.
Agent Smith can nevertheless enforce the following policy:
Capture levels
agent-ready-contextinstructs it toRole of
subagent-profile-adapterExtend
subagent-profile-adapterso its harness projections may include:The skill should:
agent-ready-context;It should not implement LangMem or the memory lifecycle itself.
Harness observations recorded along the way belong in the existing user-scoped
okf/wiki/tooling/overlay; episodes are a separate artifact class and never live there.Current harness patterns
The exact configuration must always be regenerated from current documentation.
Current examples include:
PostCompact,SessionEnd, and optional subagent completion hooks exposing local transcript or compact-summary informationPostCompact,Stop, or subagent events, with explicit hook trust and transcript-path compatibility handlingAfterAgent,PreCompress, andSessionEndsession.idle,session.compacted, or related eventsRepositoryEpisodeReferences:
These native files remain runtime projections.
They must not become a source of repository knowledge.
Capture adapter design
The harness-specific projection should be thin:
The capture hook must be:
It should not:
Example envelope:
{ "schema_version": "1", "harness": "claude-code", "event": "SessionEnd", "session_id": "abc123", "repository_root": "/workspace/project", "repository_revision": "82db174", "transcript_path": "/local/harness/session.jsonl", "compact_summary": null, "final_response": null, "captured_at": "2026-07-15T10:30:00Z" }The event records a pointer or bounded payload.
It is not yet memory.
Capture modes
Summary mode
Default mode.
Capture:
Advantages:
Transcript mode
Explicit opt-in.
The adapter may copy a transcript into the local inbox.
Requirements:
Teams that accept versioning captured material may do so only behind explicit, recorded validation by every user whose sessions are captured: per-user opt-in, a documented team policy, secret scanning before any commit, a dedicated tracked location outside
okf/wiki/, and unchanged canonical rules (raw transcript content still never reaches OKF pages). The default remains local-only.Hybrid mode
Recommended for high-quality memory formation:
The transcript provides recall.
The task summary provides salience.
The repository provides authority.
Filesystem layout
For the current OpenWiki architecture:
The memory workspace is deliberately not under
okf/.okf-build/: that root is disposable per-run staging that cleanup may wipe, while episodes are long-lived user state.okf/.langmem/(see “Configuration and secrets resolution” above) is a third, narrower ignored home: engine configuration and credentials only, never memory payload — mirroring the same separationokf/.openwiki/already draws between producer state and canonical output.Boundary:
Local memory must not live inside
okf/wiki/.That avoids:
Note: upstream’s hardcoded
openwiki/directory exists only inside the disposable stage (okf/.okf-build/<run-id>/worktree/openwiki/); it is never a live surface and never a memory location.Versioned interchange interface
Agent Smith should own a small, versioned file interface.
The canonical model definitions should be Pydantic classes shipped under
agent-ready-context.JSON Schema should be generated from those models for TypeScript and other harness adapters.
Proposed schemas:
Possible location:
RepositoryEpisodeExample:
MemoryCandidateExample semantic candidate:
Example procedural candidate:
These files are provisional memory.
They are not OKF pages or Agent Skills.
PromotionPacketExample:
This becomes the stable boundary between the sleep lifecycle and a promotion engine.
LangMem adapter
LangMem has no native OKF output and should not be modified to own one.
The adapter should translate:
Agent Smith must not expose LangMem’s internal object layout as its repository contract.
Conceptual implementation:
The first implementation should keep automatic deletion disabled.
LangMem may recommend:
The assimilating agent applies the final state transition after policy checks.
Why the OKF is not the LangMem store
It is tempting to point LangMem’s store integration at
okf/wiki/and let consolidation read and write canon directly. This is rejected:review.diff,INSTRUCTIONS.mdbyte-preservation, no-op parity) lives between candidate and canon and would be structurally bypassed rather than merely skipped;The OKF still participates — read-only: consolidation receives bounded OKF excerpts as context (
existinginput), and promotion is the only write path back. This is also why the storage-independentcreate_memory_manageris preferred overcreate_memory_store_manager: persistence stays in Agent Smith’s reviewed files, never in an engine-owned store.Provider configuration
LangMem requires a model accessible through a compatible LangChain model interface.
Agent Smith should not assume that the script can reuse a harness’s subscription session — and it must not reuse OpenWiki’s credential home:
okf/.openwiki/remains OpenWiki-owned and hands-off. LangMem credentials are a separate surface, supplied through environment variables or the user’s own configuration, disclosed like any other provider route, and never committed.Possible execution modes:
Native-agent mode
The current harness follows the same schemas and consolidation policy using its own active model.
LangMem is not invoked.
LangMem-assisted mode
An approved LangChain-compatible provider or endpoint is available.
Examples may include:
The normal Agent Smith data-flow disclosure remains mandatory.
Degraded deterministic mode
No approved semantic model is available.
The workflow may:
It must not claim that dreaming completed.
Planned helper commands and LangMem sketch (non-final)
Only
consolidate_memory.pydepends on LangMem; every other helper is stdlib-only, so capture, normalization, and validation work with no model and nothing installed.consolidate_memory.pysketch (illustrative shape, not final code):Bounded by design: one invocation, one topic region, no store, no loop, no canonical write.
--engine nativefollows the same consolidation policy using the harness’s own active model;--engine deterministicperforms only duplicate/contradiction grouping and defers semantics.Sleep lifecycle
Phase 0 — eligibility and consent
Before processing:
AGENTS.md;okf/wiki/index.md;agent-ready-contextandreferences/openwiki-lifecycle.md;Possible triggers:
post-commit) capturing an envelope;Agent Smith does not create or own the scheduler.
Phase 1 — session normalization
Convert the captured session into a
RepositoryEpisode.Inputs may include:
Normalization must:
Phase 2 — cheap episodic storage
Store the episode locally without requiring an LLM consolidation call.
This follows the recurrence-oriented principle:
Recurrence is a prioritization signal.
It is not evidence of truth.
Phase 3 — bounded selection
Select a working region based on:
Do not load the entire repository or all memory by default.
Phase 4 — consolidation
LangMem or another selected engine reviews:
It produces operations such as:
The output remains local and provisional.
Phase 5 — rehearsal generation
Generate:
Examples:
Synthetic questions are evaluations.
Synthetic answers are never evidence.
Phase 6 — verification
Semantic candidates must be checked against:
Procedural candidates must be checked for:
The consolidator must not be the sole verifier of its own output.
Prefer:
Phase 7 — evaluation
Compare:
Measure:
The migration’s existing benchmark protocol (task sets of source-grounded atomic facts, blind answer/score separation, per-fact verdicts) should be reused as the measurement harness rather than reinvented.
Phase 8 — promotion
Produce a verified
PromotionPacket.Route based on target:
Phase 9 — cleanup
After review:
OpenWiki promotion adapter (current stack)
Semantic promotion has two supported routes, both already governed by the existing lifecycle. (A third, Route 0, handles
user-toolingcandidates: they become hand-authored pages in theokf/wiki/tooling/overlay under its existing policy — local by default, one outgoing project link, never producer input — and never involve the producer at all.)Route 1 — reviewed direct edit (preferred for narrow, verified facts):
Route 2 — staged update (for broad or structural knowledge):
Route selection rubric (deterministic, applied by the operating agent):
scope: user-toolingokf/external/first)Route 1 renderer (deterministic): locate the owning page by following the
index.md→quickstart.mdrouting; apply the smallest section-level edit; append the citation (path@commit, test command/result, or URL + access date); leave every other page byte-identical; run strict OKF validation and the tooling link policy; then ordinary Git review. The preservation contract obliges the next producer run to keep the edit.Route 2 packet delivery: the packet’s statement and evidence summary travel in the wrapper’s
--printprompt for that one update run; document evidence enters the staged corpus throughokf/external/. The pre-run citation gate then forces every produced claim to cite staged paths — exactly the property that prevents a dreamed candidate from smuggling unverifiable content into the wiki.Constraints inherited from the migration (non-negotiable):
code --init|--update --printargv is permitted;okf/wiki/INSTRUCTIONS.mdis byte-preserved; dreaming never edits it;index.md/log.mdare never hand-edited and run provenance is never fabricated;Division of ownership:
OpenWiki owns:
Agent Smith owns:
OpenWiki does not currently expose a generic
PromotionPacketinterface.Possible integration approaches should be evaluated:
--printargument);The issue must not assume such an interface already exists.
Legacy reference: the
v0.1.0OpenKB promotion adapterFor the record, the pre-migration design routed verified packets through the findings lifecycle:
The renderer/packet boundary proposed here is the direct descendant of that design; only the engine-specific write operation changed.
Comparative experiment
Measure:
Procedural promotion adapter
A verified procedural packet goes to
skill-creator.Example:
skill-creatordecides:Scaffolding is deterministic (
init_skill.py+quick_validate.py); dreaming never installs or adopts a generated skill directly.Eligible targets:
Ineligible targets:
Retrieval and use during future work
The memory lifecycle should not only write memory; it should define how the next agent reads it.
Before a relevant task, an agent may receive:
Each layer has a distinct role:
Episodes should be retrieved conservatively.
Initial deterministic retrieval may use:
A disposable local index may later use:
The index must never become the only copy of memory.
Research basis
Language Models Need Sleep: Learning to Self-Modify and Consolidate Memories
Relevant lessons:
Limitation:
This work provides the overall sleep/dream lifecycle analogy.
Auto-Dreamer: Learning Offline Memory Consolidation for Language Agents
Relevant lessons:
This is the closest direct research match to the proposed external-memory consolidation architecture.
Agent Smith should adopt the architecture without recreating Auto-Dreamer’s trained consolidator.
RecMem: Recurrence-based Memory Consolidation for Efficient and Effective Long-Running LLM Agents
Relevant lessons:
This supports local episodic files and delayed consolidation.
Sleep-time Compute: Beyond Inference Scaling at Test-time
Relevant lessons:
This supports rehearsal and proactive routing improvement.
Reflexion: Language Agents with Verbal Reinforcement Learning
Relevant lessons:
For Agent Smith, these remain provisional episodes until repository verification.
ExpeL: LLM Agents Are Experiential Learners
Relevant lessons:
This informs both semantic candidate extraction and procedural skill candidates.
Remember Your Trace: Memory-Guided Long-Horizon Agentic Framework for Consistent and Hierarchical Repository-Level Code Documentation
Relevant lessons:
This is directly relevant to an OKF/OpenWiki repository memory.
Retrieval as Reasoning: Self-Evolving Agent-Native Retrieval via LLM-Wiki
Relevant lessons:
This supports mapping semantic memory to the LLM-wiki/OKF.
CoALA: Cognitive Architectures for Language Agents
Relevant lesson:
This reinforces Agent Smith’s separation between:
CoALA is also the taxonomy source the LangChain memory documentation (below) itself cites, so the vocabulary used across this issue, LangMem, and the LangChain ecosystem shares one lineage.
LangChain memory concepts
Relevant terminology:
Agent Smith should reuse this taxonomy without requiring a LangChain harness.
LangMem
Relevant implementation capabilities:
Agent Smith should integrate only through the bounded interchange layer.
Industry inspiration (non-normative): supermemory
supermemory (MIT; hosted and self-hostable) demonstrates the harness reach this issue asks of
subagent-profile-adapter: MCP-based memory tools across Claude Code, Cursor, Windsurf, VS Code, OpenCode, and OpenClaw, plus framework wrappers. Its breadth is useful inspiration for the capture-projection matrix. It is not a candidate engine here: an external memory service injecting context through MCP cannot satisfy this stack’s rules — consent-first egress per phase, OKF as the sole canonical knowledge base (memory dreams included), review-gated promotion, and hands-off credential boundaries. That is also why the capture hooks are written by the assimilating agent itself throughsubagent-profile-adapter’s projections: no third-party integration layer can be assumed compliant with these policies. LangMem remains the first-class engine, behind the file contract, installed under the same pin/TOFU/telemetry discipline as every other tool.Security and privacy
Local by default
The following remain local and ignored by default:
Canonical shared outputs remain:
Data-flow disclosure
Before any semantic model call, disclose:
Secret protection
Before model submission:
.envfiles and the OpenWiki credential home (okf/.openwiki/, hands-off);Prompt injection
Treat as untrusted data:
Instructions embedded in evidence must not override:
Memory poisoning
A local episode cannot become shared memory solely because:
Promotion requires current repository evidence.
Execution safety
Dream-generated scenarios must not authorize:
Optional scripts
Small Python and TypeScript helpers are allowed.
They remain implementation resources inside the skills, not a new Agent Smith application.
Python
Use:
with PEP 723 metadata when dependencies are needed.
Appropriate responsibilities:
TypeScript
Use a thin project plugin only when required by the active harness.
An approved Node setup may use:
fnm-managed version;pnpm.The TypeScript layer should translate native events into
SessionEnvelope.It should not implement memory consolidation.
Prohibited script architecture
Scripts must not introduce:
Commit and ignore policy
Two new ignore rules are needed (neither is covered by the existing
okf/.okf-build/entry):Tracking policy:
okf/.langmem/.env)Implementation plan
Phase 1 — policy and schema
Extend
agent-ready-contextwith:Define:
No LLM processing is required in this phase.
Phase 2 — harness capture projection
Extend
subagent-profile-adapterto generate:Implement at least two harness integrations.
Requirements:
Phase 3 — episode normalization
Implement:
Support:
No canonical writes.
Phase 4 — LangMem proof of concept
Implement a one-shot
uvhelper around LangMem’s storage-independent manager.Input:
Output:
No LangGraph server.
No Deep Agents requirement.
No direct persistence through a LangGraph Store.
Phase 5 — rehearsal and verification
Create an engine-neutral evaluation corpus:
Separate solver and verifier contexts where possible.
Phase 6 — OpenWiki promotion
Implement:
Reuse the existing staged lifecycle, citation gate, and preservation contract unchanged.
Phase 7 — procedural promotion
Route verified procedural packets through
skill-creator.Test:
Phase 8 — optional scheduling
Only after manual runs demonstrate value:
Agent Smith still does not own the scheduler.
Evaluation design
Compare:
Measure:
The migration’s benchmark methodology (pinned corpora, source-grounded atomic facts, blind answer/score separation) should be reused as the measurement protocol.
LangMem should remain preferred only if it demonstrates measurable value over a simpler agent-performed implementation.
Acceptance criteria
Product architecture
agent-ready-context.subagent-profile-adapter.skill-creator.Capture
SessionEnvelopeexists.RepositoryEpisodeexists.LangMem
Scope classification
MemoryCandidatecarriesscopeandscope_rationale.projectscope with environment-independent evidence.user-toolingcandidates promote only to theokf/wiki/tooling/overlay under its existing link policy.Filesystem
okf/.memory/, separate from disposableokf/.okf-build/staging.okf/wiki/.Semantic memory
okf/wiki/.okf/wiki/INSTRUCTIONS.md, reservedindex.md/log.md, or fabricates run provenance.Episodic memory
Procedural memory
skill-creator.Evaluation
Security and privacy
Non-goals
This issue does not propose:
Risks and open questions
Transcript stability
Some harnesses expose a transcript path but do not guarantee the internal transcript format.
Adapters must:
Hook trust and disablement
Users may disable project hooks.
Full automatic mode must validate capture availability and report degradation rather than silently claiming complete memory.
Local-memory growth
Episodes may accumulate indefinitely.
Possible controls:
False recurrence
Several episodes may share the same incorrect source or copied assumption.
Related provenance must not be treated as independent confirmation.
Self-reinforcing hallucination
A model may extract, consolidate, rehearse, and judge the same false claim.
Independent source and test verification must break this loop.
Over-consolidation
A broad semantic abstraction may erase important exceptions.
The system should preserve:
Procedural over-specialization
A workflow that succeeded once may not transfer.
Skill promotion requires multiple contexts or exceptional safety justification.
Producer churn
A high-quality candidate can still produce a low-quality producer update (page duplication, unrelated rewrites, lost caveats).
The existing review.diff review pass, deterministic validation, no-op parity gate, and manual-edit-preservation contract remain required.
OpenWiki integration
OpenWiki does not currently expose the proposed packet interface.
The initial implementation should use the bounded adapter routes above and evaluate whether an upstream interface is justified.
Ecosystem convergence (bonus investigation)
Verified: OpenWiki is a DeepAgents-based LangChain/LangGraph application, and DeepAgents already ships a
MemoryMiddleware— but its documented job is loadingAGENTS.md-specification context into the system prompt (aMemoryStatemapping source paths to loaded content, backend-abstracted over filesystem or remote storage), not extraction, consolidation, or LangMem integration. No reference to LangMem was found in DeepAgents' memory documentation.More significant: LangChain has separately shipped OpenWiki Brains, a related but distinct framework giving agents "proactive memory pulled from the tools users already work in" (Gmail, Notion, git, X, Hacker News, web search), with two modes: Personal Brain (a wiki built from connected sources, scheduled updates) and Code Brain (repository-scoped documentation maintenance — functionally adjacent to this issue's territory). No mention of LangMem was found in available coverage of Brains either, and its exact relationship to the pinned
openwikipackage (same repository, separate product, or eventual merge) is unconfirmed from public sources at this research depth.Net finding: no evidence of an existing or announced LangMem↔OpenWiki bridge. The ecosystem proximity (same vendor, same memory taxonomy origin, a second adjacent "Brains" product with real users) makes convergence plausible but unconfirmed. Standing check at every OpenWiki or LangMem pin move: inspect upstream issues/PRs for memory-integration work, and specifically re-check whether Code Brain's repository-memory approach converges with or duplicates this issue's scope. If a native bridge appears, re-evaluate Route 2 and the consolidation engine against it — the file contract and governance gates stay either way.
LangMem dependency weight
The official LangMem package currently carries LangChain/LangGraph dependencies even when used without a graph deployment.
The proof of concept should measure:
Agent Smith should not fork LangMem merely to remove those dependencies.
Shared versus private learning
Local episodes belong to individual users by default.
Only verified semantic or procedural results should become shared repository artifacts.
Team-level sharing of episodes or transcripts is permitted only behind explicit, recorded validation by every captured user, with its own poisoning controls — and still never places raw session content in canonical OKF surfaces.
Proposed initial decision
Implement a manual, report-first proof of concept inside the existing three-skill architecture.
The first milestone should:
okf/.memory/layout and its ignore policy;subagent-profile-adapterwith at least two native capture projections;PromotionPacketfiles;skill-creator;Only after this demonstrates measurable value should the project consider:
All reactions