Knowledge & Documentation

Beyond code, Synapses manages knowledge artifacts: package documentation, web references, and architectural decision records. These integrate into context packets so agents have the full picture.

Package Documentation with lookup_docs

lookup_docs retrieves Go package documentation (godoc-style) and caches it locally.

{
  "tool": "lookup_docs",
  "arguments": {
    "package": "net/http"
  }
}

Returns the package synopsis, type and function signatures, and doc comments. Results are cached so repeated lookups are instant.

Third-Party Packages

{
  "tool": "lookup_docs",
  "arguments": {
    "package": "github.com/gorilla/mux"
  }
}

URL Caching

lookup_docs also works with documentation URLs:

{
  "tool": "lookup_docs",
  "arguments": {
    "url": "https://pkg.go.dev/github.com/gorilla/mux"
  }
}

The page content is fetched, parsed, and cached. Future lookups for the same URL return the cached version.

Web Annotations with annotate(action=“add_web”)

annotate(action="add_web") lets agents persist findings from web pages — API docs, blog posts, reference material — and link them to code entities.

{
  "tool": "annotate",
    "action": "add_web",
  "arguments": {
    "url": "https://docs.stripe.com/api/charges/create",
    "summary": "Stripe charge creation requires amount (in cents), currency, and source. Returns a Charge object with id, status, and receipt_url.",
    "entities": ["internal/billing/stripe.go:CreateCharge"],
    "tags": ["stripe", "billing", "api"]
  }
}

Annotations surface in context packets when the linked entities are queried:

{
  "tool": "get_context",
  "arguments": {
    "query": "CreateCharge",
    "intent": "modify"
  }
}
// Response includes the Stripe API annotation alongside the code

Updating Annotations

Call annotate(action="add_web") again with the same URL to update the summary:

{
  "tool": "annotate",
    "action": "add_web",
  "arguments": {
    "url": "https://docs.stripe.com/api/charges/create",
    "summary": "Updated: Stripe now recommends PaymentIntents over Charges. See migration guide.",
    "entities": ["internal/billing/stripe.go:CreateCharge"],
    "tags": ["stripe", "billing", "api", "migration"]
  }
}

Architectural Decision Records (ADRs)

ADRs document significant technical decisions with their context, rationale, and consequences.

Creating an ADR

{
  "tool": "rules",
    "action": "upsert_adr",
  "arguments": {
    "title": "Use SQLite for local index storage",
    "status": "accepted",
    "context": "Need a persistent store for the code graph index. Options: SQLite, BoltDB, BadgerDB.",
    "decision": "Use SQLite via go-sqlite3. It provides full SQL query capabilities, is battle-tested, and supports concurrent reads.",
    "consequences": "CGO dependency required for go-sqlite3. Single-writer limitation acceptable for our use case. WAL mode enables concurrent reads."
  }
}

ADR Statuses

Status	Meaning
`proposed`	Under discussion, not yet decided
`accepted`	Approved and in effect
`deprecated`	Was accepted but no longer applies
`superseded`	Replaced by a newer ADR

Querying ADRs

{
  "tool": "rules",
    "action": "list_adrs",
  "arguments": {}
}

Returns all ADRs. Filter by status:

{
  "tool": "rules",
    "action": "list_adrs",
  "arguments": {
    "status": "accepted"
  }
}

ADRs in Context

ADRs automatically surface in get_context(mode="intent") and get_context responses when they are relevant to the queried entities. For example, querying about database code returns the SQLite ADR.

Knowledge Mode for Non-Code Projects

For projects that are primarily documentation, configuration, or data (not source code), enable knowledge mode:

{
  "brain": {
    "knowledge_mode": true
  }
}

In knowledge mode:

Synapses indexes markdown, YAML, JSON, and other non-code files as primary entities
The graph captures document structure (headings, sections, references)
get_context searches across documentation content
Cross-references between documents become edges in the graph

This is useful for documentation repositories, configuration management projects, or knowledge bases.

Example: Building a Knowledge Layer

1. Start a session
   session_init(agent_id="docs-agent")

2. Look up package docs for a dependency
   lookup_docs(package="github.com/redis/go-redis/v9")

3. Annotate an external API reference
   annotate(action="add_web",
     url="https://redis.io/docs/data-types/streams/",
     summary="Redis Streams: append-only log with consumer groups...",
     entities=["internal/queue/stream.go:StreamConsumer"],
     tags=["redis", "streams", "queue"]
   )

4. Record the architecture decision
   rules(action="upsert_adr",
     title="Use Redis Streams for event queue",
     status="accepted",
     context="Need a distributed event queue. Options: Kafka, RabbitMQ, Redis Streams.",
     decision="Redis Streams — already running Redis, good enough throughput for our scale.",
     consequences="Tied to Redis. No replay beyond retention. Consumer groups handle fanout."
   )

5. Future agents get all of this in context
   get_context(mode="intent", task="Add dead letter queue for failed events", intent="add")
   // Returns: StreamConsumer code + Redis Streams annotation + ADR + related episodes