AKMON v0.2.0

The first public release of AKMON. It builds a searchable knowledge graph
from your repositories, documents and services, and serves it to coding
agents (Claude Code, Claude Desktop, Cursor and Codex) over MCP, the protocol
those agents use to call tools. AKMON's Python package and command are named
okg, so every command below starts with okg.

Get it

• Python package: the wheel okg-0.2.0-py3-none-any.whl is attached to
  this release. Install it with uv tool install or pip install, then
  follow the quickstart (docs/start/quickstart.md).
• Containers and Kubernetes: the Install section at the end lists the
  runtime and PostgreSQL images and the Helm chart, each with its digest. The
  chart names both images, so an install needs no image settings
  (docs/operate/deployments/kubernetes.md).

What's new

Agents get better answers

• Search finds exact names, ticket keys and file names, and lists a file
  first when you name it. Duplicate records no longer crowd out results.
• Search results show a heading and the matching passage, not the whole
  record, and a record already shown in the session is referred to instead
  of repeated. Searches return 8 results by default.
• Search and record replies say on their first line how large they are and
  which setting makes them smaller. A reply that would be too large comes back shortened, with the
  call that reads the rest, instead of being refused.
• When a call is nearly right, AKMON answers it and says what it changed;
  otherwise it says what to change. A mistyped record id gets the nearest
  real one. Results say what they left out and where to find it.
• A read never says it is complete when it left rows out, and a condition
  with a value of the wrong type is refused instead of answered with an
  empty page.

More ways to read the graph

• Every read tool takes the same conditions, including dates, text patterns
  and an accent- and case-blind substring test, and the same field names.
• Read up to 50 records in one call, read chosen lines of a text, and count
  records per day, week, month or year, per list element or per link.
• expand returns the records a record links to, each with its type and
  title; * follows any link.
• Exact text search can list every matching record with an exact total and
  gives the line number of each match.
• The read-only SQL tool query describes the graph it serves and pages a
  large reply. It is offered when per-user access rules are off.
• Search by meaning (optional). With vector sets configured under
  embeddings in deployment.yaml, search can rank records by meaning as
  well as by words (docs/operate/configure.md, "Embeddings").

Reading from a shell

• The okg command line has one command per read tool: okg search,
  inspect, expand, filter, aggregate, map and query. Each prints
  the reply the MCP server would send, or JSON with --json, and exits 0
  when served, 2 when refused and 1 on any other failure.
• The commands take short shell forms (--where status=Open, a bare record
  id) and print rows for a pipe (--jsonl, --ids, --all); ids can be
  piped from one command into the next.
• okg <command> --help shows each tool's own description with a worked
  example, and okg guide prints the instructions an agent gets when it
  connects.

Larger answers and live services

• An agent can page through, filter and count one large answer from a live
  service (a database or API the graph connects to) without running out of
  context.
• An agent can keep a search result and come back to it later in the same
  session.
• When an agent connects, a short summary tells it what the graph holds.
• Live services that answer with a single object return it as one row.

Many agents, many users

• One server handles several agents at once without queuing them.
• With per-user access rules on, each reader sees only what they may read:
  search ranks only readable text, and a record a reader may not see reads
  as not found.

Setting up

• okg install sets up a graph in one command; okg agent connect
  connects every agent it finds. install.sh installs from a clone.
• The bundled database's port, container name and password are settings,
  and it runs under its own Compose project, okg-pg.
• okg doctor passes on a fresh install without false alarms, checks that
  each agent's saved command still exists, and fails when the newest publish
  was refused.
• An unreachable database is reported in one line that names the host and
  the setting to fix.
• When an agent can't find the database address, okg agent connect says
  where it must go and prints the command that puts it there.
• The "Run it as a service" docs lead from a working graph to a shared
  service in one path.

Keeping a graph current and safe

• okg up upgrades an installed graph: it checks compatibility, backs up the
  database and checks the backup, migrates, and writes a record of what it
  did. okg deployment backup restore puts the backup back.
• A publish blocked by the catalog's rules names the missing rule and the
  module that provides it. A publish check can name the sources it depends
  on; while one of them is off, the check is skipped and reported instead of
  blocking the publish.
• okg doctor warns when a source loses most or all of its records, and
  reports a publish schedule you paused on purpose as paused, not stale.
• Credentials that appear in stored Git diffs are hidden before they reach
  the graph, and records of deleted files say when and by which commit they
  were deleted.
• Git fixes: each commit carries its author as plain fields; turning rename
  detection on or off applies to history already read; a file that changes
  type is one change; a branch switch with no file changes moves the files to
  the new branch; an unchanged run no longer removes file records.
• Undoing a source run no longer deletes a later rerun's rows.
• The outbound-fetch allow list accepts IPv6 addresses.

Breaking changes

These change how an existing installation behaves. A new install is not
affected.

• Migrate each database once. After installing 0.2.0, run
  okg up <deployment> (or okg migrate --deployment <deployment> --apply)
  for every existing graph; the steps are below. A graph pinned with
  release.channel: prod also needs its release.pin in deployment.yaml
  updated to the 0.2.0 values; check it with
  okg deployment release <deployment> --json.
• Move keyword search to pg_textsearch 1.5.1. Existing databases keep
  version 1.3.0, which can repeat or drop keyword-search results, until you
  move them by hand. The move is one-way, so back up first; see below.
• Unknown source settings are refused. A source registry file
  (source_registry.yaml) now refuses settings AKMON does not recognise; the
  error names the setting and the closest valid one. Rename or remove it
  before upgrading.
• A sync that suddenly returns nothing now fails. When the background
  worker reads a whole source and gets no records while the graph still holds
  records from it, the sync fails on every check instead of quietly keeping
  the old records. If the source really is empty now, run
  okg ingest --inline --allow-full-retraction <source> once.
• A failed source no longer blocks publishing. A published version can now
  hold fresh data from the sources that succeeded next to older data from one
  that failed, and its ingest_completeness marker says which. okg migrate
  lifts the repair requirement the earlier behaviour left on such versions.
• okg catalog load --apply waits for, and blocks, other writes. It now
  holds the graph's write lock while it runs, so other writes to the graph
  wait until it finishes.
• Read replies changed shape. Scripts that parse replies should check
  three changes: a one-hop expand returns one row per linked record (select
  only link fields for the old one row per link); searches return 8 shorter
  results by default (set limit and max_chars for more); and under
  per-user access rules the SQL tool query is no longer offered.

Upgrading from an earlier build

Only if you ran AKMON from source before this release:

1. Install the 0.2.0 wheel, then run okg up <deployment> --plan and
   okg up <deployment>. okg up needs pg_dump and pg_restore from
   PostgreSQL 17 on your PATH; --plan checks for them.
2. Move keyword search to pg_textsearch 1.5.1 (required). Back up,
   restart the database on the 0.2.0 PostgreSQL image (the published
   akmon-postgres:v0.2.0 image in the Install section, or a rebuild of
   ops/pg), then run
   ALTER EXTENSION pg_textsearch UPDATE; in each AKMON database. Version
   1.3.0 can repeat or drop search results. okg doctor warns until this is
   done. The move is one-way; going back takes the backup.
   See docs/operate/lifecycle.md, "Upgrade to 0.2.0".
3. Expect one long Git sync. The first sync after the upgrade reads
   every Git commit again once, to store each commit's author. On a graph
   with a long Git history this took 6 to 7 minutes, then a publish of 8 to
   10 minutes, and the database grew by about 3 GB.

New installs on the 0.2.0 image need none of these steps.

Known issues

• Code parsing on a slow network. On first use, code parsing downloads
  about 500 MB of language grammars, and the download stops after about a
  minute. On a slow connection, download them in advance; see
  docs/runbooks/troubleshooting/first-run.md.
• GitHub comments. The github source's include_discussion=true
  setting fails the import (producer_node_subtype_not_allowed); leave it
  off. Issues and pull requests themselves import normally.
• Upgrade, restore and copy need PostgreSQL client tools. okg up,
  okg deployment backup restore and okg db clone need pg_dump and
  pg_restore at the database server's major version or newer (17 for the
  bundled database).
• The background worker is off by default. To keep a graph current
  without running okg ingest yourself, set runtime.enabled: true in the
  deployment's deployment.yaml, run okg runtime bootstrap, and keep
  okg runtime worker running; it checks each source every 5 minutes. With
  the worker on, okg ingest waits for it. okg doctor can report red for
  the first few minutes after the first worker starts. On Linux, okg up
  refuses a graph that has run a worker unless the worker service is
  installed (okg dogfood service install --deployment <deployment> --adapter systemd --apply) and okg up runs as root.
• Bundled database project renamed. The ops/pg Compose project is now
  okg-pg (it was pg, which could join another app's project of that
  name). If docker compose up stops with container name "/okg-pg" is already in use, that is your old database: to keep it, set
  COMPOSE_PROJECT_NAME=pg for every compose command, if no other app on the
  machine uses project pg. Its data is in the volume pg_okg_pgdata. If
  the old container is gone but that volume remains, docker compose up
  starts a new, empty database instead; the same setting reaches the old
  data.
• Agents and a password kept out of the command line. If you installed
  with --postgres-dsn '${OKG_DSN}' (single quotes, so okg reads the
  address from the environment), agents cannot see your shell's
  environment: copy the address into the deployment's .okg/local.env
  first. okg agent connect prints the exact command.
• Publishing a large code source takes about 30 minutes, and other
  updates of the same graph wait for it. On a graph of about 785,000
  records it measured 1,720 to 1,780 s. No data or search results are lost.
• A very large catch-up publish can time out. When a graph has many
  queued source updates (for example after its worker was stopped for
  days), one publish can spend longer than the 15-minute statement limit
  copying unchanged attributes forward, and the next attempt can hit the
  same limit. To let one catch-up finish, set
  publisher.hard_statement_timeout_seconds (for example 7200) in the
  deployment's deployment.yaml; also set
  publisher.allow_raised_statement_timeout: true so the readiness checks
  accept the longer limit. Restore the default after it publishes. Normal
  publishes and new installs are not affected.
• The viewer's read pages need a token only when you ask for one.
  Started the default way, python -m okg.viz and the operator console
  (okg ui) show graph data to anyone who can reach their port, and on a
  shared machine every account can reach 127.0.0.1. Start them with
  --auth-token-env VARIABLE_NAME, as for the MCP server, to require the
  token in that variable for the read API (/viz/api/); okg ui
  requires it for pages too. okg ui listens on loopback only.
  python -m okg.viz refuses a network address unless both this token and
  OKG_VIZ_OPERATOR_TOKEN are set. Operator controls always need
  OKG_VIZ_OPERATOR_TOKEN.
• With access rules on, search can still hint at hidden text. When a
  deployment uses per-user access rules and a search matches many rows the
  reader may not see (from about 2,000), the shape of the answer (how many
  results come back, how the page ends, whether a count is exact) can differ
  from a search for a word nobody stored. No hidden text is returned, but a
  reader can learn that a word exists somewhere they cannot read. If the
  existence of a term must stay secret, keep that data in a separate
  deployment rather than relying on access rules alone.

Install

Everything below was built from the commit this tag names. The tags v0.2.0 (images) and 0.2.0 (chart) are never moved or overwritten; pin a digest to be certain.

Artifact	Reference	Digest
Runtime image	ghcr.io/mitdbg/akmon:v0.2.0	sha256:26be91d9963e49cb8199cf4683047703ad35335360bed885e9b01693e086b537
PostgreSQL image	ghcr.io/mitdbg/akmon-postgres:v0.2.0	sha256:f1f6ed76eb1b2d6587b341f297b3aa630eaf2f282fc5538f8129cf48e4866355
Helm chart	oci://ghcr.io/mitdbg/charts/akmon version 0.2.0	sha256:2152a11d1565d870ad3592406eecae6e5d715aae0381fc9ec380e0c3b7abf8b2

helm install okg oci://ghcr.io/mitdbg/charts/akmon --version 0.2.0 -f values.yaml

The chart's appVersion is v0.2.0: with images.okg.tag and digest empty it runs ghcr.io/mitdbg/akmon:v0.2.0, and its PostgreSQL image is ghcr.io/mitdbg/akmon-postgres:v0.2.0.