🧠 MemoryAgent — Qwen Cloud Persistent Memory for Codebases

A persistent memory agent powered by Qwen Cloud, built for the Global AI Hackathon 2026 (Track 1: MemoryAgent).

Files don't just contain code — they report their identity. Projects don't just have files — they know their purpose. Tasks don't just log — they prove their outcome. Humans ask across layers through the Envoy interface.

This is not chat-history caching. It is a persistent, self-updating codebase world model that agents reason over — powered by Qwen Cloud APIs for semantic extraction, cross-file synthesis, and intelligent query routing.

---

✨ What's built (status)

Layer	Status	Notes
File Memory	🟢 Done	memory/file_metadata.py (Qwen extraction — mock fallback if no key) + memory/tablestore.py (real OTS client w/ file-backed mock)
Project Memory	🟢 Done	memory/project_knowledge.py → project#qwen-tome, ttl_days=30
Task Memory	🟢 Done	memory/task_state.py + memory/tome_agent.py Tome hook (on_task_complete)
Envoy (CLI)	🟢 Done	envoy/cli.py: recall-file, recall-project, recall-task, route (+ --verbose provenance)

See TODO.md for the day-by-day plan and TRACK_1.md for the full architecture, cost budget, and demo script.

---

🏗️ Architecture

Human ──▶ Envoy CLI / HTTP (Alibaba Cloud Function Compute)
│
▼
Project Orchestrator (Tome)
│
┌──────────┼───────────────┐
▼ ▼ ▼
File Project Task
Memory Memory Memory
(Tablestore: pk, summary_json, ttl_days, saved_at)
│
▼
Qwen Cloud API ◀── extraction + reasoning + query routing
(qwen3.6-flash via OpenAI-compatible API)

All memory is persisted in Alibaba Cloud Tablestore (OTS) — the deployment stage for this Qwen-powered agent. Each record carries its own ttl_days + saved_at so every layer expires independently (logical TTL).

---

🧠 How It Works

1. Qwen extracts structured semantics from files (language, purpose, tests, conventions)
2. Memories persist in Tablestore with per-layer TTL — surviving across sessions
3. Envoy routes natural-language queries to the right memory layer using Qwen reasoning
4. Knowledge compounds — the LLM Wiki (wiki/) maintains a human-facing, interlinked markdown knowledge base

---

🚀 Getting Started

# 1. Create a virtualenv and install deps
pip install -r requirements.txt
# 2. (Optional) Set up credentials via .env
cp .env.example .env
# Fill in QWEN_API_KEY and ALIYUN_* vars (see .env.example)# Without credentials, everything runs in mock mode — fully functional.# 3. Run a recall
python -m envoy.cli recall-file main.py
python -m envoy.cli recall-project --save
python -m envoy.cli recall-task add-tablestore
python -m envoy.cli route "Which files handle memory?"# Qwen-powered cross-layer routing

Until credentials are configured, the system degrades to an in-memory mock — the CLI is fully usable end-to-end with no API keys at all.

---

📖 LLM Wiki — the narrative knowledge tier

Alongside the structured memory in Tablestore, this repo ships an LLM Wiki — Karpathy's pattern (see LLM_WIKI.md): a persistent, interlinked markdown wiki Qwen maintains from raw sources in wiki/raw/. It's the human-facing counterpart to the agent-facing Tablestore rows.

python -m wiki.cli ingest raw/<file># source → summary + entity pages + index
python -m wiki.cli query "What does Tablestore store?"
python -m wiki.cli query "Summarize the architecture" --file # file answer back
python -m wiki.cli lint # orphans / stale claims

---

📁 Project Structure

memory/
file_metadata.py # Qwen extraction of file semantics
project_knowledge.py # Qwen-powered cross-file synthesis
task_state.py # verified outcomes → persistent task memory
tome_agent.py # Tome Agent subclass; on_task_complete → auto-log
qwen.py # Qwen Cloud client: real call via OpenAI-compatible API
tablestore.py # Alibaba Cloud Tablestore backend + mock fallback
webhook_handler.py # Git-push auto-refresh via FC
envoy/
cli.py # Human interface: recall-file / recall-project / recall-task / route
wiki/ # LLM Wiki — Qwen-maintained narrative knowledge tier
plans/ # Day-by-day build plans
AGENTS.md # Agent strategy ↔ Track 1 judging criteria
TRACK_1.md # Architecture, cost budget, demo + Devpost script
TODO.md # 7-day execution plan

---

🏆 Why This Wins Track 1

• Innovation & AI Creativity (30%) — Sophisticated use of Qwen Cloud APIs for semantic extraction, cross-file synthesis, and natural-language query routing. Qwen does the reasoning, not just extraction.
• Technical Depth & Engineering (30%) — Multi-layer memory with per-record TTL and cross-layer recall routing, persisted in Tablestore. Clean abstractions, mock fallbacks, smoke tests.
• Problem Value & Impact (25%) — Solves real dev pain: onboarding, context-switching, forgotten conventions — for any Python/JS/TS repo.
• Presentation & Documentation (15%) — A <3 min terminal demo showing four distinct recalls, plus architecture diagram and full docs.

---

🔐 Security & Submission

• .env is never part of the submission. It is gitignored. The public repo ships .env.example — a secret-free template.
• Alibaba Cloud deployment proof lives in source: from tablestore import OTSClient + *.aliyuncs.com endpoint in memory/tablestore.py.
• Qwen Cloud API key is optional — without it, the system uses mock responses for all Qwen calls.
• Deployment gets secrets from the environment, not from files — Function Compute injects vars at runtime.