Your agent remembers

Every sprint makes the next one faster.

The problem

Without nanostack, every sprint starts from zero. The agent does not remember that it spent 20 minutes debugging a timezone bug last week, or that your project uses a specific error handling pattern, or that the team decided to avoid ORMs. You end up re-explaining the same context every session.

Three document types

The knowledge base stores three types of structured documents in .nanostack/know-how/:

  • Bugs— root cause, symptoms, and fix for issues encountered during sprints. Stored in know-how/solutions/bug/.
  • Patterns— recurring implementation patterns specific to your project. Error handling conventions, naming rules, file structure decisions. Stored in know-how/solutions/pattern/.
  • Decisions— architectural choices with rationale. Why SQLite over Postgres, why server components over client, why no ORM. Stored in know-how/solutions/decision/.

How knowledge flows between sprints

Here is a concrete example:

Sprint 1: Build habit tracker
  /review finds: streak calculation breaks across timezone boundaries
  /compound saves: know-how/solutions/bug/timezone-streak-calc.json
  {
    "type": "bug",
    "title": "Streak breaks across timezone boundaries",
    "root_cause": "Date comparison used UTC midnight, user is in PST",
    "fix": "Normalize all dates to user's local timezone before comparison",
    "files": ["src/routes/streaks.ts"],
    "tags": ["dates", "timezone", "streaks"]
  }

Sprint 2: Add daily reminders
  /nano runs find-solution.sh during planning
  Finds timezone-streak-calc.json (tag match: "dates", "timezone")
  Plan includes: "Use user timezone for reminder scheduling
  (see know-how/solutions/bug/timezone-streak-calc.json)"
  The agent avoids the same mistake without you saying anything.

Staged retrieval

Knowledge retrieval happens through bin/find-solution.sh. It runs in three stages to avoid flooding the agent with irrelevant context:

  1. Tag match— compares tags from the current task description against document tags. Fast, high precision.
  2. File overlap— checks if any planned files overlap with files referenced in existing documents. Catches related work even when tags differ.
  3. Recency rank— among matches, newer documents rank higher. A bug fix from last week is more relevant than one from three months ago.

The result is a ranked list of at most 5 documents. The agent reads the top matches and incorporates them into the plan.

Solutions evolve

Solutions are not static snapshots — they are compiled truth. Every time /compound confirms that a solution was applied in a sprint, it:

  • Marks it as validated: true
  • Increments applied_count
  • Updates last_validated
  • Appends a History entry explaining what happened

The rewritable sections (Problem, Solution, Prevention) get updated with new information. The History section is append-only: an evidence trail of how the understanding evolved.

validated: true
last_validated: 2026-04-11
applied_count: 3
## History

### 2026-04-11 — Validated in sprint nanogstack-20260411
Applied during /review. Prevention rule caught the issue before production.

### 2026-04-05 — Updated solution
Original fix was incomplete. Added mutex locking.

### 2026-04-01 — First documented
Found during /qa. Two concurrent saves corrupted session.json.

Why this matters: find-solution.sh ranks validated solutions higher. A solution applied 5 times ranks above a critical-severity solution nobody tested. Knowledge gets better with use.

Pattern detection

bin/pattern-report.sh reads all sprint artifacts and detects patterns across sprints:

  • Recurring findings— tags that appear in review or security findings across multiple sprints.
  • Risk accuracy— did the risks predicted in /think actually materialize in review/security findings?
  • Phase bottlenecks— which phases consistently take the longest.
  • Solution reuse— how often existing solutions are referenced versus new ones created.
Pattern Report (2026-04)

  Recurring findings:
    auth-validation         3 occurrences
    missing-error-handling  4 occurrences

  Risk accuracy:
    Predicted: 5
    Materialized: 2 (40%)

  Phase durations (avg):
    review    120s
    think      45s

Staleness check

Documents older than 90 days get a staleness flag. The agent still reads them, but it will note that the information might be outdated. If a stale document gets referenced in a sprint, the /compound phase asks whether to refresh or archive it.

You can adjust the staleness threshold in your config:

// .nanostack/config.json
{
  "knowledge": {
    "staleness_days": 60
  }
}

Sprint journal

Every sprint produces a journal entry in .nanostack/journals/. The journal captures what was built, what was decided, and what was deferred. Unlike the knowledge base (which stores reusable solutions), the journal is a chronological record of sprint activity.

// .nanostack/journals/2026-03-28-habit-tracker.json
{
  "date": "2026-03-28",
  "feature": "habit-tracker",
  "phases_completed": ["think", "plan", "build", "review", "security", "qa", "ship"],
  "files_changed": 6,
  "issues_found": 2,
  "issues_fixed": 2,
  "knowledge_created": ["solutions/bug/timezone-streak-calc.json"],
  "deferred": ["user authentication", "habit categories"]
}

The deferred list feeds back into /thinkon the next sprint. When you say "add auth," the agent already knows it was deliberately deferred and why.

Previous← ConflictsNextToken usage →