Codebase Wiki

Architectural knowledge base with MCP interface for AI agents.

Agents discover services, generate LLM-powered docs with Mermaid C2/C3/sequence diagrams, and index them for semantic search. Includes self-learning notes and first-class workflow/flow indexing.

Quick Start

npm install -g @carreira-cloud/codebase-wiki

cd my-project
codebase-wiki init              # Initialize knowledge base
codebase-wiki serve             # Browse at http://localhost:3080
codebase-wiki start-mcp         # Start MCP server for AI agents

Commands

Command	Description
init	Initialize knowledge base for current repo
serve	Start web UI (markdown + mermaid rendering, flows tab)
start-mcp	Start MCP server (stdio JSON-RPC, 12 tools)
search <query>	Search docs, notes, and flows by keyword
get <service>	Retrieve full documentation for a service
list	List all indexed services
stats	Statistics: services, flows, notes, content size
install-opencode	Install OpenCode skills and commands

MCP Tools

Documentation (8 tools)

Tool	Description
wiki_index	Index an LLM-generated architectural document
wiki_search	Search documentation by keyword
wiki_get	Retrieve full documentation for a service
wiki_list	List all indexed services
wiki_delete	Remove a service's documentation
wiki_stats	Statistics: services, content size, notes count, flows count

Self-Learning Notes (3 tools)

Tool	Description
wiki_note	Store a self-learning discovery note
wiki_notes_search	Search agent notes by keyword
wiki_notes_list	List notes (optional type filter)

Workflows & Flows (3 tools)

Tool	Description
wiki_flow_index	Index a workflow diagram with keywords and linked services
wiki_flow_search	Search flows across all services by keyword
wiki_flow_list	List flows (optional service/flow_type filter)

OpenCode Commands

/wiki generate <service>       → Agent discovers, generates docs, indexes via MCP
/wiki generate-all              → Generate docs for all services
/wiki enhance <service> <flow>  → Add Mermaid C3/C2/sequence diagrams
/wiki discover-flows <service>  → Discover and index all workflows with edge cases
/wiki flow-search <query>       → Search flows across all services
/wiki flow-list <service>       → List flows for a service
/wiki search <query>            → Search docs + notes + flows
/wiki get <service>             → Retrieve full doc
/wiki list                      → List all indexed services
/wiki stats                     → Knowledge base statistics

Self-Learning

Agents automatically add notes when they discover something new. Six note types:

Type	Trigger
gotcha	Unexpected behavior, edge case, known bug
pattern	Recurring pattern across 2+ services
integration	Undocumented service integration detail
convention	Code convention, naming pattern
decision	Design decision (lightweight ADR)
tip	Shortcut, useful command, workflow hack

Flows & Diagrams

Each flow is independently indexed with:

• Mermaid sequence diagram (happy path + error paths + edge cases)
• Keywords for discoverability
• Linked services for cross-service navigation
• Flow type: happy_path, error_path, edge_case, recovery, full

Diagrams render in the web UI via Mermaid.js. The UI also renders service documentation markdown (tables, code blocks, headings) via marked.js.

Architecture

src/
├── cli.ts              # CLI entry (8 commands)
├── mcp-server.ts       # MCP JSON-RPC server (12 tools)
├── ui-server.ts        # Web UI (marked.js + mermaid.js, flows tab)
├── lancedb/client.ts   # JSON file-backed storage (docs, notes, flows)
├── types.ts            # TypeScript types
└── index.ts            # Public API exports

docs/
├── getting-started.md
├── mcp-tools.md
├── self-learning.md
├── configuration.md
└── architecture.md

Storage: .codebase-wiki/rag_db/docs.json + notes.json + flows.json

License

MIT — Bruno Carreira