Waymark is the open-source, self-hosted memory for your team and its AI agents. It turns your repos,
trackers, docs and chats into one searchable, source-linked knowledge base. Next, it will run AI teammates
that work from that knowledge, on the agent runtime you already have.
Quick start · MCP server · Claude Code · Cursor · Hermes · Docker
Real output of waymark sync and waymark search on this repository, trimmed for width.
AI agents are only as good as the context they get.
- Code-intelligence tools know what the code is.
- Agent platforms know how to run an agent.
- The why lives in PR reviews, issue threads, design docs, incidents and chat. So does who owns which system, and how data flows from one service to the next. Most of that never reaches the agent, or the new hire.
Waymark collects that knowledge and keeps it as plain markdown you own. It serves it back to people and agents, with a link to where every fact came from.
- One search across sources. Commits and repo docs, GitHub PRs, reviews and issues, Linear, Jira, Confluence, Notion, Discord and Azure DevOps work items, pull requests and wiki pages today; Slack and Teams are next (#20).
- Answers with receipts. Every hit links back to the commit, PR, issue or page it came from.
- Memory for your agents. Hooks capture Claude Code, Cursor and Hermes sessions, and a new session starts with what the last one learned. Agents can leave a handoff that exactly one later session claims.
- Plain files you own. The wiki is markdown in a git repository; the SQLite index (full-text plus optional vectors) is rebuildable at any time with
waymark reindex. - No LLM required. Sync, search, capture and handoffs work offline with zero API keys. Semantic search is an opt-in upgrade with any OpenAI-compatible embeddings endpoint, including a local one (docs/search.md). An optional OpenAI-compatible
llmfor text generation stays optional too (docs/memory.md). - Its own identity. Waymark reads each source as its own app or service account, never as you (ADR-0002, setup per source).
- Who touched what.
- Every commit, PR and repo doc is indexed with the files it touches and who touched them, as authors, reviewers and commenters.
- One person is recognised across git names, logins and chat names;
waymark experts <path>ranks who to ask with evidence (docs/memory.md).
- Ready for a team.
- Users, groups, linked chat identities and API tokens, with only token hashes stored (ADR-0003).
- A chat-bot runtime with user mapping and rate limits (docs/bots.md).
A teammate is an AI agent your team configures in Waymark, starts from a chat mention or the CLI, and points at a playbook. Here is an example.
Someone notices that a day of currency data is blank and mentions the bot in Teams. The teammate uses the system map to see that the data comes from service X, which is fed by CDC replication from another database. It works through the chain:
- It checks the API, the service database and the source database, and finds the gap in the replication.
- It reads the CDC project's logs and code, and finds the commit that introduced the bug.
- It replies in the thread with the evidence, or files a card for a human with the full write-up.
What Waymark provides:
- the teammate's identity;
- the triggers;
- playbooks with stages, budgets and routing;
- the knowledge;
- a default-deny, audited gateway to your tools;
- structured verdicts that must cite real evidence.
What stays with you:
- the agent itself (Claude Code, Hermes Agent or any CLI agent), on your own machine or VM, through pull-only runners that need no inbound port;
- your model keys;
- your sandbox;
- your infrastructure.
Waymark never runs model-generated code itself. The design is ADR-0004 and the work is tracked in #116. The first phase is investigate-and-report. Proposing fixes as pull requests comes later.
| Layer | What it needs | Waymark |
|---|---|---|
| Brain | Code, docs and decisions, the same for people and agents | ✅ today: connectors, hybrid search, MCP, hooks, handoffs, path facts |
| Identity | Apps and bots that act as the system, not as a person | ✅ today: own identity per source, users and tokens |
| Work intake | Chat mentions, trackers, alerts | 🚧 chat bots (#19) |
| Control | Playbook contract, dispatch, routing | 🔜 teammates (#116) |
| Execution | Agent runtime, sandbox, tools | Yours. Waymark plugs in through runners and a tool gateway (#116) |
| Quality | Evidence-checked verdicts, audit, evals | 🔜 verdicts and audit (#116, #94); evals later |
Waymark is meant to sit alongside the tools you already use:
- MCP servers. Any of them, including code-search and code-intelligence servers, can become a teammate tool behind the gateway.
- Agent platforms. Any platform that speaks MCP can use Waymark as its memory.
Node 24 is required. The package is not on npm yet.
git clone https://github.com/AlanEdward19/waymark && cd waymark
npm ci && npm run build && npm link
waymark init # creates ~/.waymark (config, wiki, index)Add sources to ~/.waymark/config.json:
{
"version": 1,
"sources": [
{ "id": "my-repo", "type": "git", "path": "C:/code/my-repo" },
{ "id": "my-repo-gh", "type": "github", "repo": "me/my-repo", "auth": "personal" }
]
}Then sync and ask:
GITHUB_TOKEN=$(gh auth token) waymark sync
waymark search "why sqlite"auth: "personal" is the quickest way to try it. For real use, give Waymark its own identity (docs/identities.md).
claude mcp add waymark -- waymark mcpThat gives Claude Code the search, who_knows, get_document, save_note and handoff tools. Add the lifecycle hooks to capture sessions as well: Claude Code · Cursor · Hermes Agent · any MCP client.
| Source | type |
What is ingested | Identity |
|---|---|---|---|
| Git repository | git |
Commits and markdown docs (include: ["commits", "docs"]) |
Local checkout |
| GitHub | github |
PRs with reviews, issues with comments | GitHub App |
| Linear | linear |
Issues and comments | OAuth app (client credentials) |
| Jira Cloud | jira |
Issues and comments (project or jql) |
Atlassian service account |
| Notion | notion |
Pages shared with the integration | Internal integration |
| Discord | discord |
Messages of configured channels, one doc per channel per day | Bot |
| Azure DevOps | azure-devops |
Work items, PRs with reviews, wiki pages (opt-in) | Entra app identity |
| Confluence Cloud | confluence |
Current pages in configured spaces (spaces: ["ENG", "OPS"]) |
Atlassian service account |
| Slack, Teams | In progress, see #20 |
Secrets never go in config.json; they come from environment variables listed per source in docs/identities.md. auth: "personal" (development only) uses a personal token where the source supports it and logs a warning.
All commands
| Command | What it does |
|---|---|
waymark init |
Create $WAYMARK_HOME (default ~/.waymark) with config.json, wiki/ and db/ |
waymark sync [--source <id>] |
Pull new and changed documents from every source (or one) |
waymark search "<query>" |
Ranked, source-linked results |
waymark show <id> |
Print one document |
waymark embed |
Embed new or changed documents (when embeddings is configured) |
waymark reindex |
Rebuild the index from the markdown wiki |
waymark mcp |
MCP server over stdio |
waymark hook <harness> |
Lifecycle hook handler for claude-code, cursor or hermes |
waymark llm test |
Check the optional llm setup (see docs/memory.md) |
waymark experts <path> [--since <days>] [--limit <n>] [--source <id>]... [--json] |
Rank people who know a file or directory, with evidence (docs/memory.md) |
| `waymark audit [--since ] [--until ] [--user ] [--event ]... [--outcome ok | denied |
waymark people [--json] |
List person names seen in the index, grouped by canonical name (see people in docs/memory.md) |
waymark user ... / waymark token ... |
Manage users, groups, linked identities and API tokens (see docs/server.md) |
waymark bot test <platform> ... |
Run the chat-bot pipeline with a console adapter (see docs/bots.md) |
- ✅ MVP: git and GitHub ingest, markdown wiki, full-text search, MCP server
- ✅ Hybrid retrieval: embeddings, rank fusion, recency (#15)
- ✅ Agent hooks and handoffs for Claude Code, Cursor and Hermes (#17)
- 🚧 More connectors with Waymark's own identity (#20), validated against real accounts (#77)
- 🚧 Organisational memory (#16): path facts, people aliases, expertise and supersession flags shipped; conventions and conflict-aware ranking next
- 🚧 Permissions, auth and remote access (#18): users, tokens and local audit shipped; team server and access control next
- 🚧 Chat bots (#19): runtime shipped; Teams, Slack, Discord, GitHub and Linear next
- 🔜 AI teammates on your own runtime (#116, ADR-0004)
Waymark is self-hosted and model-agnostic. It works with no LLM at all, it never trains on your data, and it never runs your agents' code: your runtime does.
Search and ranking · Organisational memory · MCP server · Claude Code · Cursor · Hermes Agent · Docker · Identities per source · Team server: users and tokens · Chat bots · ADR-0001 stack · ADR-0002 own identity · ADR-0003 team server · ADR-0004 teammates
Issues and pull requests are welcome. Read CONTRIBUTING.md, open an issue to discuss bigger ideas first, and report vulnerabilities privately (SECURITY.md). npm run check (lint, types, tests) must pass.