Best Practices & Conventions

Best Practices

1. Knowledge Structuring

• Use descriptive document titles (e.g. Auth Service Architecture instead of Notes).
• Link related concepts with [[wikilinks]] to enrich the Knowledge Graph.
• Keep documents modular (<2,000 words per document) for optimal vector chunking and retrieval precision.

2. Secrets Management Hygiene

• Organize secret paths hierarchically (e.g. /production/database/url, /staging/auth/jwt_secret).
• Always specify meaningful audit reasons when revealing secrets.
• Use path-scoped API keys with minimal required scopes (doc:read instead of *:*).

3. Optimizing AI Agent Interaction via MCP

• Instruct agents to perform hybrid search before assuming knowledge does not exist.
• Use graph_find_path to discover indirect relationships across distributed subsystems.