A System 1 for AI agents: instead of hoping the model remembers to search, put the right experience into the context before the task starts.
English | ç®€ä½“ä¸æ–‡
Agents solve every task as if it were the first. The pitfall you hit last week, the bypass you found, the project convention that never made it into the docs: the next run starts from zero. Cognitive Enzyme stores such experience as small rules ("enzymes"), injects them automatically at the right moment, and gets more accurate as feedback arrives about whether each one actually helped.
Slides (Chinese): Tencent Security Salon #8, Beijing — an Agentic vulnerability-research practice built on the "cognitive enzyme" self-evolving architecture
| Problem | What it looks like | What Cognitive Enzyme does |
|---|---|---|
| Tacit knowledge is never written down | The model does not know how to write a file through Jackson in a given setup, so it takes the generic path | Stores it as a rule with "when to use" and "what to do", and injects it passively before the task, so the model is not left to guess |
| Models give up early | On a dead end they declare "not exploitable"; one answer is enough for them | A rule can carry process constraints such as "try at least two more bypasses before giving up" |
| Active search gets skipped | The model forgets to search, or searches with the wrong words | Hooks retrieve before the prompt and again on a tool error, with no cooperation from the model |
| Skill piles grow without bound | Dozens of fixed skills slow the model and overfit it | Only the few rules activated by the current situation are injected, then pruned by feedback |
Two ideas are borrowed:
- Dual-process theory (Thinking, Fast and Slow). System 1 is fast, automatic pattern matching; System 2 is slow and deliberate. An LLM's reasoning is System 2. This project adds the missing System 1: "this situation reminds me of that lesson".
- Cue → Routine → Reward, the structure of an enzyme. Each memory has a when (the triggering situation) and a how (the behavior). The learning signal is not the reward itself but the difference between reward and expectation, a dopamine-style error: help reinforces, harm weakens.
One cycle:
- prime (before the prompt). Retrieve with the current situation: vector recall, BM25 lexical recall and matches against past situations; rerank; then an applicability judge scores each candidate with "probability this is directly useful for the request" and decides which memories to inject and how many. Injecting nothing is a valid outcome.
- failure (on a tool error). Retrieve again with the raw error text and surface fixes that worked before.
- capture (session end or before compaction). Extract "error → fix" experience from the session, pass it through a quality gate, dedupe it and file it under a domain.
- feedback and consolidation. The agent reports whether an injection helped; memories are reinforced or weakened. A scheduled job merges duplicates, quarantines weak ones and produces unverified hypotheses (dream, mutation, crossover) that get a small exploration budget.
Unlike people, there is no time decay: an agent does not need to forget, only to keep what matters. Memories are quarantined by quality (zombies that keep failing, contradictions), not by age.
Requires Python 3.11+, Node.js 20.9+ and Docker (for PostgreSQL and Qdrant).
cp .env.example .env
# Option 1: full stack in Docker (set CE_GHCR_OWNER to the account or org that hosts the images)
CE_GHCR_OWNER=<your-account> bash scripts/deploy.sh
# Option 2: storage in containers, app on the host (development)
bash scripts/dev-up.shOpen http://localhost:13000. The admin user is admin; set the password with CE_ADMIN_PASSWORD, otherwise a random one is generated on first start and printed in the server log. Then:
- Change the password (account settings).
- Models → Providers and models: add a provider and models. A chat model and an embedding model are required; rerank and judge are optional and degrade gracefully.
- Models → Bindings: assign a model to each stage.
- Settings → Access and security: create a static API token for the hooks.
API docs: http://localhost:8420/docs. Health: /health, /readyz.
| Agent | Mechanism | Install |
|---|---|---|
| Claude Code | hooks (prime / failure / capture) | npx -y cognitive-enzyme-hook install --url http://<server>:8420 --token <API token>; see hooks/npm/README.md |
| pi | extension in hooks/pi/ |
ln -s $PWD/hooks/pi ~/.pi/agent/extensions/cognitive-enzyme; see hooks/pi/README.md |
| Any agent | REST / MCP | POST /api/prime (with source, cwd, project); MCP at :8421/mcp exposes prime, search, recall, report, harvest |
Every integration is fail-open: if the backend is down, slow or errors, the hook silently does nothing and never blocks the agent.
tests/eval/ holds recall benchmarks and a framework for the harder question: does an injected memory make the model answer correctly? The numbers below come from one experiment on competition math and physics problems that a model had already failed twice closed-book (147 questions; 64 of them have an annotated correct memory, 83 question-memory pairs). Reproducing it needs the datasets, which are not shipped (see the scripts in tests/eval/hardbench and tests/eval/diagnostic).
1. Recall: the right memory was mostly lost before the judge ever saw it.
With the default settings the judge's request budget is spent on the first few candidates, so the judge sees a median of 4 candidates out of a nominal pool of 36. Of the 65 annotated memories that reached the candidate pool, only 7 were judged.
Judging the whole pool (judge.two_stage with judge.two_stage_compare=joint and judge.scan_pool=36) raises "injected" from 6 to 26. Adding an RRF-built pool, no rank cut-off at rerank and wider recall (judge.pool_order=rrf, ranking.rerank_keep=floor, recall.dense_limit=100, recall.cap=120) reaches 31. The cost is more judge calls (13 to 17 per prime instead of 1) and more injected memories per question (0.58 before, 1.35 and 2.14 after).
2. Answers: injecting more did not make the model answer better.
For the same questions, a solver (MiniMax M3.1 Flash; the same model grades) answered closed-book and again with each injection setting.
- Even handing the model the annotated correct memory rescued 1 question and harmed 3 (n = 63).
- Injecting more memories rescued slightly more and harmed more. No difference is statistically significant (McNemar p between 0.34 and 0.63).
- Closed-book answers are themselves noisy: in earlier runs of a different model (GLM-5.3), 56 of 353 physics questions (16%) flipped between two identical closed-book attempts. These counts sit inside that kind of noise.
What this supports: recall can be made far more complete, but on these hard problems a retrieved memory is not the same as a useful one. The memories we have for them are mostly method hints, and a hint does not carry a model past a problem it cannot solve. What it does not show: that injection does not help in general. This was one solver, one judge model, a hard problem set and small counts. Treat the recall change as ready to try and the answer-level effect as unproven.
Other caveats worth knowing:
- Recall is limited by several count-based cut-offs in the pipeline (rerank keep, judge pool, the judge's per-request token budget). Memories with long bodies hit them sooner. The relevant knobs are under
ranking.*,judge.*andrecall.*. - The new recall options default to the previous behavior. Nothing changes until you turn them on.
- Datasets (competition problems, public corpora) are not distributed with this repository. Build them with the scripts and follow each dataset's license.
About 100 parameters for models, recall, judging and learning are edited in Settings → Runtime and take effect on save. Environment variables are only for what is needed before the database is reachable: PostgreSQL, the first admin and the Qdrant address.
To add a parameter, add one entry to SPECS_LIST in app/settings.py; it appears in the console automatically and is read in code with settings.get("<key>").
| Path | Contents |
|---|---|
app/ |
Backend: matching/ recall and judging, learning/ the learning loop (capture, consolidation, dreams), distill/ decision records and teacher labels, routers/ REST |
hooks/ |
Claude Code hooks (Python and npm package) and the pi extension |
webui/ |
Admin console (Next.js + shadcn/ui): memories, recall debugging, evolution events, model bindings, runtime settings, audit |
ops/gardener/ |
Nightly gardener: a headless agent in a container that re-checks memories against the codebase |
scripts/ |
Deployment, local development, evaluation and diagnostic scripts |
tests/ |
Unit tests; tests/eval/ holds the recall and effect benchmarks |
python -m pytest tests --ignore=tests/eval # backend unit tests
node --test hooks/pi/ # pi extension tests
cd webui && npm run typecheck && npm run lint # frontend- The initial admin password is random (or set by
CE_ADMIN_PASSWORD); change it after first login. Static API tokens only open the data-plane endpoints and can be rotated in the console. The MCP server generates a token on first start and stays closed without one. - Login is rate-limited (10 attempts per IP and account per 5 minutes); disabling a user or changing a password invalidates old JWTs immediately.
docker-compose.ymlmounts the Docker socket into the app for the nightly gardener. Access to that socket is root on the host, which is acceptable only for a single-user internal deployment. Delete the two mount lines if you do not need the gardener..env,webui/.env.localand~/.config/cognitive-enzyme/hook.envare never committed.
GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
If you modify this software and offer it as a network service to others, you must make the complete modified source available to those users. The admin console uses only open-source components such as shadcn/ui (MIT) and lucide-react (ISC).