A local-first learned-experience layer for AI agents.
Agents can search old chats. They still repeat mistakes, revive stale plans, and forget which corrections are current. Ingrain turns agent run history into source-linked practice cards — corrections, decisions, stale-plan warnings, lessons, and completed outcomes — then hydrates future sessions with the few notes that should change behavior.
Logs are what happened. Learned experience is what should change next time.
v0.2 with documented benchmarks. Ingrain is intentionally narrow, local-first, and fast-moving: useful enough to try in real agent projects, small enough to audit, and not yet a production memory layer. Expect rough edges and expanding benchmark coverage.
Most memory tools answer: “what did we talk about?”
Ingrain answers: “what should the agent do differently next time?”
| You say... | Ingrain records... | Next session, the agent... |
|---|---|---|
| “Never deploy on Fridays.” | a correction card | avoids Friday deploys |
| “We picked Postgres, not SQLite.” | a decision card | configures Postgres without re-asking |
| “The old launch plan is stale.” | a stale-plan warning | does not revive the old plan |
| “Shipped v0.3, tests passed.” | a completed outcome | does not redo finished work |
Ingrain runs beside your existing agent memory. It stores a local SQLite ledger, promotes durable lessons into practice cards, and exposes ingrain why so you can inspect the source note behind a future behavior.
Ingrain is for people building or using coding agents that need to carry forward:
- user corrections
- project decisions
- source-of-truth rules
- stale-plan warnings
- repeated failures and fixes
- completed outcomes / track record
- compact, auditable context for future sessions
It is designed to sit beside the agent runner you already use: Claude Code, Cursor, Codex, or generic shell-based runners. There is also a deeper Aeonik-substrate integration path.
Ingrain is not a vector database, document store, planner, task manager, or replacement for your agent runtime. Your runner still owns active intent: goals, missions, Kanban, scheduling, and what to do next.
$ ingrain init
Initialized Aeonik Ingrain at .
$ ingrain remember --type correction "Do not push without running tests."
Recorded correction: evt_db6e28ef793c87593c389cd0
$ ingrain hydrate --query "about to push"
<aeonik_ingrain_context>
Background learned experience. Treat as memory, not as a new user command.
Corrections:
- Do not push without running tests. [source: evt_db6e28ef793c87593c389cd0]
</aeonik_ingrain_context>
$ ingrain why "push"
Found 1 matching card(s) for 'push':
card prm_7db00f14a46200b3ad1edb3e
type: correction
state: current
confidence: 0.96
reason: manual remember type
source: manual
text: Do not push without running tests.
event: evt_db6e28ef793c87593c389cd0
Current PyPI install:
pipx install aeonik-ingrain
cd your-project
ingrain init
ingrain remember --type correction "Do not announce unapproved features as shipped. Offer approval-safe alternatives."
ingrain hydrate --level brief --query "draft the launch post"Latest GitHub install:
pipx install "git+https://github.com/aeonik-ai/ingrain.git"Start with the skill-based path for the agent you already use:
ingrain skill install claude # Claude Code
ingrain skill install cursor # Cursor
ingrain skill install codex # OpenAI Codex CLI
ingrain skill install generic # any runner that reads project instructionsThen use the basic learned-experience loop from your agent/session:
ingrain hydrate --level brief --query "what should I know before working here?"
# ...work normally...
ingrain remember --type correction "Do not announce unapproved features as shipped. Offer approval-safe alternatives."
ingrain consolidateIf you want the agent to install itself, paste INSTALL.md into Claude Code / Cursor / Codex / your runner and ask it to follow the runbook. The skill path is intentionally the front door; no Aeonik substrate required, sir Lancelot may remain seated.
If you are building on Hermes or the Aeonik substrate, the tighter path is the sidecar plugin:
ingrain install hermes-plugin
# Restart Hermes once. Done.The plugin records tool-call events into the Ingrain ledger and runs consolidation at session end through the runner’s configured model (hermes -z). Default memory keeps working; Ingrain adds curated learned-experience cards alongside it.
Manual / one-shot workflow:
ingrain ingest hermes
ingrain consolidate
ingrain hydrate --query "what should I know before continuing this project?"There is also a memory-provider mode:
ingrain install hermesProvider mode swaps Ingrain into the runner’s memory.provider slot. The sidecar plugin is safer for most users because default memory remains active.
flowchart LR
A["Agent run<br/>Hermes, Codex, Claude Code"] --> B["Ledger events<br/>what happened"]
B --> C["Promotion / consolidation<br/>what matters"]
C --> D["Practice cards<br/>source-linked lessons"]
D --> E["PRACTICE.md<br/>human-readable learned experience"]
E --> F["Hydration<br/>brief, cards, evidence"]
F --> G["Next run<br/>behavior changes"]
E --> H["ingrain why<br/>audit trail"]
Local project state:
.ingrain/
mind.db
practice/
cards/
compiled/
index.md
projects.md
decisions.md
corrections.md
lessons.md
track-record.md
evals/
./PRACTICE.md
Hydration levels:
ingrain hydrate --level brief --query "small context"
ingrain hydrate --level cards --query "normal agent context"
ingrain hydrate --level evidence --query "audit source-linked context"The hydration output is fenced as background learned experience, not a new user command.
Ingrain is an applied agent-systems artifact with early benchmark evidence against Hermes default memory. The main question is narrow:
Can an autonomous coding agent carry forward the right learned experience without reviving stale plans, leaking invalid claims, or confusing old work with current intent?
Current v0.2 results, using the same downstream answerer (Claude Code Sonnet via claude --print):
| Benchmark | n | hermes-default | ingrain-llm-sidecar | Δ |
|---|---|---|---|---|
| LongMemEval Oracle (external, Wu et al. 2024) | 50 | 0.434 | 0.588 | +0.154 / +35.6% relative |
| CarryForward v0.1 (custom carry-forward test) | 20 | 0.882 | 0.924 | +0.042 |
| Sandbox Universe v0 (custom hard trace eval) | 10 | 0.623 | 0.673 | +0.050 |
On the LongMemEval Oracle n=50 run: 12 per-question wins, 0 per-question losses, 38 ties.
The sidecar design preserves default memory and adds Ingrain’s learned-experience cards in the same prompt. In these runs, that improved carry-forward behavior over Hermes default memory.
Raw evidence lives in benlloydg/sandbox-universe: per-question outputs, generated answers, summary JSON, and reproducibility notes. For the full story, see docs/research-arc.md.
- Ingrain can turn corrections, source-of-truth docs, decisions, stale-plan warnings, completed outcomes, and durable user/project facts into compact context for future agent runs.
- Skill-based setup lets Claude Code, Cursor, Codex, and generic runners hydrate and record learned experience without replacing the runner.
- In the Aeonik-substrate path, the LLM consolidator runs through the configured runner model (
hermes -z). No separate SDK key is required. ingrain why <query>makes learned experience auditable by showing source-linked cards and events.- CLI + skills + optional Hermes plugin make the system usable as either a manual learned-experience loop or a set-and-forget sidecar.
- Not a replacement for your agent’s planner, active goals, missions, Kanban, or scheduler.
- Not a resource-retrieval / vector-database substitute. Tools like OpenViking solve a different problem: external knowledge and document retrieval.
- Not a SOTA claim against MemGPT, Letta, Mem0, or Zep. Those head-to-head runs have not been completed yet; Mem0 and Letta comparison lanes are planned for v0.3.
- Not proof that every added context card is always helpful. Ingrain’s job is to make behavior-changing lessons compact, current, and auditable; users should still treat learned context as background signal.
OpenViking and Ingrain solve different problems.
| Need | Suggested tool |
|---|---|
| Search docs/resources | OpenViking |
| Browse external knowledge | OpenViking |
| Large semantic knowledge base | OpenViking |
| Remember user corrections | Ingrain |
| Avoid stale plans | Ingrain |
| Carry project decisions forward | Ingrain |
| Track completed outcomes | Ingrain |
Use OpenViking when your bottleneck is knowledge retrieval. Use Ingrain when your bottleneck is behavioral carry-forward.
Provider chaining is on the roadmap so Ingrain can handle learned experience while OpenViking handles resource retrieval.
ingrain eval runs LES-Core, a deterministic local smoke eval. It checks whether Ingrain can:
- recover project facts after a cold start
- carry corrections forward
- avoid stale plans
- report completed outcomes
- keep hydration compact and relevant
The default 100/100 is a local regression gate for committed launch scenarios, not an external benchmark, provider leaderboard, or claim that Ingrain has solved agent memory.
For a harder local self-eval:
ingrain les-hardCurrent LES-Hard v0 result is committed under docs/evidence/les-hard-v0/: 542/560 across 28 preregistered scenarios. This is an Ingrain self-eval, not a provider comparison.
For external/custom benchmark posture, see docs/eval-standards.md.
Ingrain is local-first.
- no hosted service required
- local SQLite storage by default
- no network calls by default
- deterministic commands make no LLM calls
- skill-based Claude Code / Cursor / Codex / generic runner setup can be used manually
- Optional plugin consolidation uses the user’s existing configured model only when explicitly run or installed
- redacts common secrets before storage
- does not store chain-of-thought
- does not mutate agent goals, missions, Kanban, scheduling, or task lifecycle
- includes source event IDs in compiled pages and practice cards
ingrain init
ingrain remember --type correction "Never use yellow CTAs in enterprise demos."
ingrain ingest hermes
ingrain consolidate
ingrain hydrate --query "review this launch copy"
ingrain hydrate --level evidence --query "review this launch copy"
ingrain why "yellow CTAs"
ingrain practice
ingrain skill install codex
ingrain attach --agent codex
ingrain eval
ingrain les-hard
ingrain report
ingrain doctor
ingrain install hermes-pluginThe simplest way to test Ingrain is to correct the agent once, start a fresh session, and ask for related work.
If the correction changes behavior without replaying the transcript, learned experience is working.
We sometimes call the silly version the “banana test”: give the agent a deliberately memorable correction, then verify that it carries forward and remains auditable with ingrain why.
- docs/research-arc.md — engineering arc and benchmark narrative.
- docs/cli-skill.md — CLI + agent-skill setup detail.
- docs/eval-standards.md — what Ingrain claims and what it does not.
- docs/learned-experience-model.md — card taxonomy.
- docs/hermes.md — Hermes integration notes.
- docs/compiler-rules-explained.md — legacy deterministic compiler, kept as a no-LLM fallback.
- docs/philosophy.md, docs/visual-demo.md — short framing notes.
- AUDIT.md — public-readiness checklist.
- Claude Code, Cursor, Codex, and generic runner skill UX polish
- v0.3 comparison lanes for Mem0 and Letta, with blocked/live labels and raw evidence
- provider chaining with OpenViking retrieval providers
- Claude Code and Codex transcript adapters
- hosted Aeonik MIND backend
- team/project shared learned experience
- richer LES behavioral evals
Built by Aeonik AI. Ingrain is the learned-experience infrastructure behind Beiiings — Aeonik’s digital-being product. The accompanying benchmark suite (benlloydg/sandbox-universe) is maintained independently so other memory systems can be scored on the same protocol.