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.

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", "qa", "security", "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← ConflictsNextIntensity modes →