sage-knowledge

Knowledge Management

You have access to a knowledge base of stored insights, decisions, and research findings. When a query relates to stored knowledge, relevant items are automatically injected into your context.

How It Works

Knowledge items are stored with keyword triggers. When your query matches those triggers, the relevant knowledge is automatically recalled and injected.

You'll see a notification like:

Knowledge recalled (2)
   - gdpr-summary (~450 tokens)
   - consent-patterns (~280 tokens)

What Gets Stored as Knowledge

Knowledge items capture durable insights useful across sessions:

Type	Example
Research conclusions	"GDPR Article 6 requires explicit consent for AI training"
Validated decisions	"We chose PostgreSQL over MongoDB because..."
Domain expertise	API patterns, regulatory summaries, technical constraints
User preferences	"Prefers academic sources", "Wants concise answers"
Project context	Tech stack, architecture decisions, constraints

Storage Structure

~/.sage/knowledge/
  index.yaml              # Registry with triggers
  {knowledge-id}.md       # Knowledge content files

<project>/.sage/knowledge/
  index.yaml              # Project-scoped registry
  {knowledge-id}.md       # Project-scoped knowledge

Knowledge Item Format

Each item has:

• id: Unique identifier (kebab-case)
• keywords: Trigger words for matching
• skill: Optional skill scope (empty = global)
• content: The actual knowledge (markdown)
• source: Where it came from (optional)
• item_type: knowledge | preference | todo | reference

Adding Knowledge

Via MCP Tool

sage_save_knowledge(
    knowledge_id="gdpr-summary",
    content="GDPR Article 6 requires...",
    keywords=["gdpr", "privacy", "consent"],
)

Via CLI

sage knowledge add notes.md --id gdpr-summary --keywords "gdpr,privacy,consent"
sage knowledge add api-guide.md --id api-patterns --keywords "api,rest" --skill web-dev

Via Conversation

Say "save this as knowledge" or "remember this" after discovering something worth preserving.

Querying Knowledge

Automatic

Just ask questions. If your query matches stored knowledge, it's injected automatically.

Manual

sage_recall_knowledge(query="what you're working on")

Test Matching

sage knowledge match "How does GDPR affect our API?"

Managing Knowledge

Update existing:

sage_update_knowledge(
    knowledge_id="the-id",
    content="Updated content",
)

Mark as outdated:

sage_deprecate_knowledge(
    knowledge_id="the-id",
    reason="Superseded by new architecture",
)

Hide from recall:

sage_archive_knowledge(knowledge_id="the-id")

Delete permanently:

sage_remove_knowledge(knowledge_id="the-id")

Behavior

• Automatic: Knowledge is recalled based on query keywords - no explicit request needed
• Additive: Multiple items can be recalled if relevant (up to token limit)
• Scoped: Skill-specific knowledge only appears when using that skill
• Transparent: Always shows what was recalled and token cost

Presenting Output

MCP tool results return structured data. Always format Sage outputs nicely in your response rather than relying on raw tool output.

Knowledge Items

When presenting recalled knowledge:

## 📚 jwt-auth-pattern
*Source: auth system analysis*

JWT authentication uses access/refresh token pairs. Access tokens are
short-lived (15min), refresh tokens longer (7 days). Store refresh tokens
in httponly cookies, access tokens in memory only.

**Code References:**
- `auth/tokens.py::create_access_token` — implements token generation
- `auth/tokens.py::create_refresh_token` — implements refresh flow

Code Links

When knowledge links to code, show the chain:

The rate limiting implementation is in `auth/middleware.py:RateLimiter`:
- Uses sliding window algorithm
- 5 attempts/minute per IP, 20/hour
- Lockout triggers email notification

Multiple Items

For multiple items, use a compact summary first:

Found **3 relevant items**: jwt-auth-pattern, rate-limiting, session-handling

### jwt-auth-pattern
[content]

### rate-limiting
[content]

Staleness Indicators

Watch for staleness indicators in code links:

• [!] — Code has changed since knowledge was saved; may need review
• [+] — Code supports the knowledge
• [~] — Code provides context

Failure Memory (v4.0)

Track what didn't work to avoid repeating mistakes.

Recording Failures

sage_record_failure(
    failure_id="jwt-localstorage",
    approach="Storing refresh tokens in localStorage",
    why_failed="XSS vulnerability - any JS can read localStorage",
    learned="Use httpOnly cookies for refresh tokens",
    keywords=["jwt", "refresh", "token", "localstorage"],
)

Listing Failures

sage_list_failures(limit=10)

Presenting Failures

## ⚠️ jwt-localstorage
**Approach:** Storing refresh tokens in localStorage
**Why failed:** XSS vulnerability - any JS can read localStorage
**Learned:** Use httpOnly cookies for refresh tokens

Failures are automatically recalled at session start when relevant to the current context.

Knowledge Linking (v4.0)

Connect related knowledge items:

sage_link_knowledge(
    source_id="auth-patterns",
    target_id="jwt-security",
    relation="related",  # related | supersedes | contradicts | extends
    note="Both cover authentication best practices",
    bidirectional=True,
)

When recalling linked knowledge, show the connections:

## auth-patterns
[content]

**Links:**
- → jwt-security [related] — Both cover auth best practices
- → oauth-integration [extends] — OAuth builds on these patterns