Scarwarden

Agent memory that cites its sources. An open-source memory engine for Qwen agents where every rule cites the exact experiences that taught it. Memory you can audit is memory you can trust.

Comment

The problem: every agent is a permanent intern

Every agent you have ever deployed forgets you at midnight. You pay for that amnesia on every run: re-explained context, repeated mistakes, and a human babysitting output that should have improved weeks ago. Teams do not distrust agent memory because it is empty. They distrust it because it is a black box: when an agent claims to "remember" something, nobody can check where that memory came from or whether it is still true.

What Scarwarden does

Scarwarden is an open-source memory engine (MIT) that turns a Qwen agent into a seasoned operator with an audit trail.

  • Episodic ledger. Every action, outcome and human correction is logged as an episode in SQLite. Append-only ground truth: nothing in memory exists without a paper trail back to this table.
  • Distillation with enforced provenance. qwen3.6-flash compresses the ledger into playbook rules as strict JSON. The hard rule sits in scarwarden/distill.py: a rule that cannot cite real episode IDs from the ledger is dropped. No provenance, no rule.
  • Deterministic, provenance-first recall. No vector database in the primary path. Queries are tokenised, stemmed, stopword-filtered and matched against rule tags. Every hit returns the rule and the episode IDs that taught it. Only the top matched rules travel to the model, so critical memories are recalled within a small context window instead of dumping the whole ledger into the prompt.
  • Confidence router. Recall is graded, never blind. A strong hit is ACT (follow the rules and cite them). A partial hit is ACT_AND_FLAG (act, but state assumptions). No relevant memory is ASK_HUMAN: the agent asks instead of guessing, and the human's answer becomes a new episode. Asking is a memory write, not a failure.
  • Agent loop with inline citations. With memory on, qwen3.7-plus answers the task and must cite every applied rule inline, like [PB-01, learnt in ep1, ep14]. Click any rule in the audit UI and it opens the actual episodes behind it, including the human corrections, word for word.
  • The amnesia toggle. One switch turns memory off live. The same model gets the same task cold and produces a generic template answer. Flip it back on and the citations return. The difference between the two answers is the product.
  • Git-diffable playbook. Every distillation pass exports the playbook to PLAYBOOK.md, versioned in git. You can diff the agent's mind.

How the judging criteria are met

Technical Depth & Engineering (30%). A complete memory lifecycle in a deliberately small, dependency-light codebase (Flask is the only dependency): write (ledger), compress (distillation), retrieve (deterministic recall), apply (cited answers), audit (UI). Two Qwen models are split by cost and role through one client module: qwen3.6-flash as the distillation workhorse, qwen3.7-plus for user-facing answers. Provenance is enforced in code at write time, not promised in a prompt: distill.py validates every cited episode ID against the ledger and drops rules that fail. Recall is engineered, not embedded: stemming, a stopword filter tuned to kill function-word false matches, tag-weighted scoring, and a graded router.

Innovation & AI Creativity (30%). Most memory agents answer "what do you remember?" Scarwarden answers "prove it." Provenance-first recall inverts the usual design: instead of a vector store you hope retrieved the right thing, a deterministic index where every recall is explainable, loggable and reproducible. The confidence router treats asking the human as a first-class memory operation. The amnesia toggle makes the whole claim falsifiable live, in one click, in front of the judge. The architecture is modular by design: ledger, distiller, recall, agent and UI are separate modules with clean seams, and the engine is domain-agnostic (the seed ledger covers two unrelated workloads, content distribution and support triage, in one schema).

Problem Value & Impact (25%). Memory is the infrastructure gap under every agent in every track, and auditability is what blocks memory from being trusted in production, in any regulated or brand-sensitive workflow. Scarwarden is the anti-black-box position: built to be adopted, MIT licensed, SQLite plus Flask, one environment variable, running locally in four commands. The roadmap (Reviewer QC retakes, Qwen3-VL visual audit, an MCP server so any Claude or Qwen agent can mount Scarwarden as a tool) extends the same principle: nothing enters memory, and nothing ships, without a citation trail.

Presentation & Documentation (15%). The README takes a stranger from fresh clone to a running audit UI in four commands. The demo video is built on binary, provable moments, not vibes: the toggle flips, the citations appear, the click-through lands on a real human correction. The architecture diagram maps the exact modules in the repo. A build-log blog post documents the honest journey, including what was descoped and why.

Alibaba Cloud deployment proof

All model calls go through Alibaba Cloud Model Studio via the DashScope international OpenAI-compatible endpoint (dashscope-intl.aliyuncs.com). The single client module, linked as the proof file: https://github.com/azaniansky-design/scarwarden/blob/main/scarwarden/alibaba_cloud.py

How it maps to the MemoryAgent brief

  • Episodic memory storage and retrieval: the SQLite ledger plus deterministic provenance recall.
  • Increasingly accurate decisions across sessions: human corrections become episodes, episodes distil into rules, rules steer every future answer, with citations.
  • Recalling critical memories within limited context windows: only the top matched rules enter the prompt, never the raw ledger.
  • Timely forgetting: every rule carries a version and a retired flag, and each distillation pass rewrites the playbook from the current ledger, so rules the evidence no longer supports do not survive the rewrite.

What's next

The 8-day build was scoped by a feature freeze: the Reviewer QC loop (the agent rejecting its own drafts with rule citations), Qwen3-VL visual audit of campaign images, the MCP server, and a replayed benchmark curve on weeks of real production sessions were all designed, and all cut to protect the core. They are the roadmap, not the claim. What shipped is the part that has to be right first: memory with a paper trail.

Try it

git clone https://github.com/azaniansky-design/scarwarden.git cd scarwarden pip install -r requirements.txt export DASHSCOPE_API_KEY=sk-... # Alibaba Cloud Model Studio python seed_data.py python -c "from scarwarden import distill; print(distill.distil())" python app.py # open http://127.0.0.1:5054

All seed data is synthetic (a fictional content team, Northstar Media). No real or personal data anywhere in the repository.

Built With

Share this project:

Updates