Thaliyola

Thaliyola (തളിയോല) is Malayalam for the palm-leaf manuscripts Kerala used to write knowledge down and keep it for the next generation.

A shared team knowledge base exposed as a remote MCP server. Every Claude client on a team reads and writes the same knowledge: systems, metrics, runbooks, project design docs, API contracts and UI/UX specs, plus the findings from past investigations.

The server holds no LLM. Clients (Claude Code, claude.ai, scheduled agents) do the reasoning; Thaliyola stores, searches, validates and versions. Agent-written content goes through human review before it is published.

| Dashboard | Knowledge graph | Project view for a frontend session | |---|---|---| | | | |

Concepts

Scopes

| Scope | Holds | |---|---| | team | Org-wide systems, metric definitions, runbooks, team decisions | | one per project | Project overview, design docs, decisions, API contracts, screen specs, project findings | | library | Reusable items shared across projects: UI component specs, design tokens, UX and tech patterns, shared contracts |

A project can declare that it uses an item from the library or from another project; that item then appears in the project's context and search results.

Components. A project can have several codebases (backend, frontend, mobile, ...). API contracts link the component that provides them to the components that consume them. When a contract or a shared design changes, consumers get an impact notice that shows up the next time an agent loads the project context.

Design knowledge.

• Item types: design tokens, UI component specs, UX patterns and screen specs.
• Attachments: screenshots and token files, which can also be embedded in markdown with ![alt](asset:<id>).
• Figma: frames are linked as source links. Figma stays the visual source of truth; Thaliyola holds the reviewed intent and rules.
• Wiring: a screen spec uses library UI components and depends_on the API contract it calls. A change to either reaches the teams that depend on it as an impact notice.

Articles and findings. Articles are curated, long-lived documents written to a template per type. Findings are episodic: incidents, RCAs, known issues, data gotchas, query recipes.

MCP tools

| Tool | Purpose | |---|---| | search_knowledge | Hybrid keyword and semantic search over article sections and findings. Defaults to the current project + team + library | | get_article | One article, or one section of it, with relations, source links and entities | | get_finding | One finding with relations, source links and review history | | browse_kb | Folder tree of articles in a scope | | list_projects | Projects with components and owners | | get_project_context | Cold-start context for an agent in a project or component: overview, contracts, impact notices, recent decisions, shared items it uses, known issues | | list_impact_notices / ack_notice | Upstream contract or shared-design changes a project or component hasn't handled yet | | list_review_queue | Pending and decided proposals (mine: true for your own) | | get_article_template | Expected sections for an article type | | list_stale_entries | Entries not verified recently and articles past their review date | | list_suggestions | Recurring root causes to fold into an article (with a suggested target), and unlinked near-duplicate findings | | get_asset | A screenshot, exported frame, token file or spec attached to an item. Images come back as MCP image content the agent can look at |

Write tools. Every write is a proposal that a person reviews before it is published:

| Tool | Purpose | |---|---| | propose_finding | Capture a confirmed root cause, incident, known issue, data gotcha or query recipe. Returns near-duplicates instead of storing when it finds them | | update_finding | Propose changes to a finding | | create_article | Propose a new article of any type | | propose_article_edit | Propose new text for one section of an article. On approval, components consuming a contract and projects using a shared item get an impact notice | | promote_finding | Propose folding a recurring finding into an article section | | verify_entry | Mark an entry still valid (applied immediately), or propose that it is superseded | | link_entries | Add a typed link: uses, provided_by, consumed_by, depends_on, related, same_root_cause, supersedes | | add_source_link | Attach a Figma frame, PR, Sentry issue or dashboard to an item | | upload_asset | Attach a screenshot (PNG/JPEG/WebP/GIF), token JSON, markdown or PDF. Text files are redacted; images can't be | | share_to_library | Propose publishing a project item to the library. On approval by a library owner, a copy (with its links and files) is created and the project is linked to it |

Repository documentation tools. The agent reads the code; Thaliyola keeps the plan, the pages, the grounded facts and what changed:

| Tool | Purpose | |---|---| | docs_begin | Start or resume a run for a repository at a commit. For updates, takes the changed files and returns the pages and facts they affect, or a no-op | | docs_submit_plan / docs_next_page / docs_skip_page | The ordered pages for the run, handed out one at a time with their current text and facts | | docs_submit_page | A whole page plus its claims, each with evidence (repo://path#L40-L82). Mermaid diagrams are checked; owners' pages publish directly, others go to review | | docs_finish | Records the documented commit and returns the managed AGENTS.md block | | docs_inspect_claims / resolve_claims | A page's facts with links to the exact source lines, and marking stale ones re-checked or retired | | get_agents_md_block | The <!-- THALIYOLA:START --> block to keep in the repository's AGENTS.md / CLAUDE.md |

File storage

Uploaded files are content-addressed and stored either on local disk (ASSET_DIR, the default) or in any S3-compatible service: AWS S3, Cloudflare R2, MinIO or Garage. Use S3 when several Thaliyola servers share files or the disk isn't durable:

ASSET_STORE=s3
S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com   # or https://s3.<region>.amazonaws.com, http://minio:9000, …
S3_REGION=auto                                         # R2: auto; AWS: the bucket's region
S3_BUCKET=thaliyola-assets
S3_ACCESS_KEY_ID=…
S3_SECRET_ACCESS_KEY=…
# S3_PREFIX=thaliyola/          optional key prefix
# S3_PATH_STYLE=false       virtual-hosted URLs (bucket.endpoint); default true suits most self-hosted servers

Requests are signed with AWS Signature V4 using Node's built-in crypto (no AWS SDK). Signing was tested against a server that verifies signatures strictly. Files are always served through Thaliyola, which checks permissions, so the bucket stays private.

Performance

Search finds candidates through indexes first (GIN for full-text, HNSW for vectors), then applies scope, status and permission filters to just those candidates. Measured on a 2-vCPU container with synthetic data (apps/server/test/perf.bench.ts):

| Knowledge base | Project search (keyword / hybrid) | Search everything | Duplicate check | |---|---|---|---| | 30k chunks (~4k articles, 10k findings) | 46 / 60 ms | 114 ms | 145 ms | | 90k chunks (~12k articles, 30k findings) | 110–150 ms | 220–430 ms | 105 ms |

Query embedding with the local model adds about 10–40 ms. Searches made only of very common words cost the most, because full-text ranking scales with the number of matching chunks.

Freshness

Knowledge goes stale:

• Flagging: a maintenance job in the server marks published entries not verified for STALE_AFTER_DAYS (default 90; STALE_AFTER_DAYS_ARTICLES to differ for articles) as possibly_stale. They rank lower and carry a warning.
• Needs attention: stale entries and articles past their review_due date appear on the home page and through list_stale_entries until someone verifies or fixes them.
• Housekeeping: the same job cleans up expired sessions and OAuth artifacts. It runs every MAINTENANCE_INTERVAL_HOURS, on one instance at a time.

Search

Search is hybrid. Postgres full-text relevance and embedding similarity are each normalized against the query's best hit and combined, then boosted for published and current-project items. Unlike rank-only fusion, this keeps how much better a hit is, so a boost can't lift a weak match over a much stronger one. Embeddings come from a small model (bge-small-en-v1.5, int8) that runs in-process on CPU. It is not an LLM, needs no API key, and is downloaded once (~35 MB). New text is embedded in the background, so writes stay fast.

• "card processor is throttling us" finds the payment-provider rate-limit RCA, even though they share no keywords.
• Duplicate detection uses the same embeddings: a reworded copy of an existing finding is flagged. Thresholds were calibrated on real text and can be tuned (DUPLICATE_SIMILARITY, SEARCH_MIN_SIMILARITY, SEARCH_SIMILARITY_WINDOW).
• Small embedding models put most text in a narrow similarity band. So a meaning-only hit must be above a floor and close to the best meaning match for the query, and it weighs less than hits that also share the query's words.
• EMBEDDINGS=off falls back to keyword search only, e.g. for machines without internet access.

On every write the server:

• redacts secrets and personal data (keys, tokens, passwords, connection-string credentials, JWTs, emails, phone numbers) with fixed rules, and refuses a write when a required field held nothing else;
• checks the version you read. Writes based on a stale version are refused with the current content.

Web UI

The server also serves a web UI at / for people:

• Dashboard: knowledge added per week, agent vs. web activity, freshness, knowledge by type, top contributors, recently approved changes and items needing attention. Every chart has a table view and hover details.

• Knowledge graph: an interactive map of how projects, components, contracts, designs, library items and findings link. Hover to trace links, click to open, zoom and pan; unlinked items are hidden until asked for.

• Relationships: every article and finding page shows a local graph of its connections within two links. "Open in graph" focuses the full graph on it, and project pages link to their own graph.

• Browse: team, library and project scopes, each with a folder tree.

• Project view: pick a component (backend, frontend, ...) to see the contracts it provides and consumes, upstream changes it still has to handle, the shared library items it uses, recent decisions and known issues.

• Search: results are highlighted, and a hit jumps to the matching section. The search box shows the best matches as you type (the last word also matches as a prefix), and the results page opens with an answer card: the single best section or finding, quoted from the knowledge base (never generated), marked "Best answer" when both keywords and meaning match and "Closest match" otherwise. The home page has an "Ask Thaliyola" box for questions.

• Command palette: ⌘K / Ctrl+K searches knowledge and entities, asks, and jumps to pages, scopes, favourites and recent items, or switches theme. / focuses the search box.

• Favourites and recent: star any article, finding or project to pin it to the sidebar (stored per person on the server); the last items you opened are listed under Recent (stored in your browser).

• Entity pages: every system, table, metric or service tagged on an item has a page listing what mentions it and what it's often mentioned with (/#/entity/metric/Conversion rate; aliases resolve).

• Links: copy a link to any article s