Axiom Meridian

Index

0. Project fact sheet
1. General product description
2. System architecture
3. Data model
4. API specification
5. User stories
6. Work tickets
7. Pull requests

0. Project fact sheet

0.1. Your full name:

Juan Manuel Rojas González ([email protected])

0.2. Project name:

Axiom Meridian — "Code drifts. Meridian doesn't."

0.3. Brief project description:

An MCP (Model Context Protocol) server that centralizes a team's institutional technical knowledge — coding rules and lessons learned — and delivers only the slice relevant to the current task, instead of forcing AI agents to read entire knowledge-base files on every session.

0.4. Project URL:

Not applicable (MCP) — Axiom Meridian is an MCP server for local use (stdio) or, optionally, HTTP/SSE bound to 127.0.0.1; there is no publicly reachable deployment URL.

0.5. Repository URL or compressed file

https://github.com/abeljumanuel/axiom-meridian-project

1. General product description

1.1. Objective:

Teams that work with AI coding agents accumulate institutional knowledge as long Markdown files: coding standards per language/framework, architecture decisions, and "lessons learned" from production incidents. This works while the files are small, but as they grow it creates three problems: every agent session re-reads the whole file even when only two or three rules apply to the current task (context and latency cost), relevance is all-or-nothing (there's no notion of "this project uses Quarkus, that one uses Spring Boot"), and there is no governance (anyone can edit the file directly, with no review or traceability).

Axiom Meridian solves this by indexing rules (RN-*) and lessons (LL-*) in an atomic block format, resolving a scope hierarchy (project → framework → language → global) to decide what applies to a given project, and serving only that filtered subset — optionally ranked by semantic relevance — through typed MCP tools. The Markdown files remain the single source of truth, and every change goes through explicit human approval.

More detail in Project Charter and Product Description.

1.2. Key features and functionality:

1. Scoped knowledge queries — query_rules / query_lessons resolve a project's effective scope chain, apply category/severity/tag filters, and return only active, matching entries.
2. Atomic, traceable format — every rule or lesson is a self-contained Markdown block (## RN-JAVA-011, ## LL-PSP-003) with structured fields, deterministically parseable and indexable.
3. Governed lifecycle — extraction and legacy-file migration never write directly to active knowledge; everything lands first in pending_proposals, and approve_proposal promotes the change to the Markdown file and the SQLite index in a single transaction.
4. PR and feature auditing — audit_pr surfaces the relevant rules/lessons before a merge; check_feature_against_rules does the same during the planning phase.
5. Meeting transcript extraction — extract_rules_from_transcript / extract_lessons_from_transcript turn meeting notes into candidate proposals.
6. Hybrid retrieval (SQL + RAG) — when embeddings exist, queries rank by semantic similarity (BAAI/bge-small-en-v1.5 via ChromaDB); when they don't, it transparently falls back to SQL filtering, without changing the tool's signature.
7. Access control and audit log — every tool is gated by an access level (read / analyze / write); every invocation is recorded, excluding sensitive parameters.
8. Ecosystem skill generation — generate_project_skills emits .claude/skills/ files following the agentskills.io convention.

Full list in Product Description § Core Capabilities.

1.3. Design and user experience:

By design, Axiom Meridian has no graphical interface of its own: it is an MCP server consumed programmatically by AI agents (Claude Code, VSCode, OpenCode, Kimi CLI) through tool calls, not by a human user navigating screens. The current "user experience" is that of an agent invoking a tool and receiving a scope-filtered JSON response.

A read-only visual panel for a human (knowledge curator or platform admin) to inspect the server's state without writing scripts — server health, scope hierarchy, rule/lesson counts, pending proposals, an embedding projector — is under construction: it is a component explicitly contemplated in the backlog, not part of the current baseline. See US-H1 — Inspect Meridian's status and contents visually (Epic H) and its associated ticket, TICKET-017.

1.4. Installation instructions:

Meridian is a Python 3.11+ package (axiom-meridian) installed with uv, which fetches a compatible Python on its own. Being a standard MCP server, it can be consumed by any protocol-compatible IDE or CLI (Claude Code, VSCode, Cursor, OpenCode, Kimi CLI), but it is optimized for and tested primarily against Claude Code.

macOS / Linux — one-line install:

curl -fsSL https://raw.githubusercontent.com/abeljumanuel/axiom-meridian-project/main/scripts/install.sh | bash

Any OS, Windows included (PowerShell or a terminal with uv installed):

uv tool install axiom-meridianmeridian setup     # detects and configures your MCP clients, creates the knowledge basemeridian doctor    # read-only check of the installation

On Windows, install uv first with powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"; no installer script is needed there, since meridian setup is plain Python.

install.sh is a thin wrapper around those same commands: it installs uv if missing (after asking), runs uv tool install, and hands off to meridian setup, which asks before configuring each detected client (Claude Code, VSCode, Cursor, OpenCode, Kimi CLI), never overwrites existing knowledge-base files or registrations that point at a different install, and finishes with meridian doctor. Run from a clone (bash scripts/install.sh), it installs that checkout in editable mode.

Claude Code plugin (server + usage skill in one unit): /plugin install meridian --marketplace abeljumanuel/axiom-meridian-project.

Semantic search is optional: install axiom-meridian[rag] (~900 MB of ML libraries) to rank free-text queries by meaning; without it, queries fall back to SQL filtering and generate_embeddings returns a RAG_NOT_INSTALLED error.

KNOWLEDGE_BASE_PATH is optional — Meridian auto-creates the knowledge base directory if it isn't set (~/.local/share/meridian on Linux, ~/Library/Application Support/meridian on macOS, %APPDATA%/meridian on Windows). Per-client configuration, upgrading, installing from source, and troubleshooting: docs/installation.md.

2. System Architecture

2.1. Architecture diagram:

Meridian follows a layered architecture: MCP tool registration → domain tool layer → parsers/RAG/persistence, with a single write choke point (write_block) that keeps the SQLite index in sync with the Markdown files. This pattern was chosen because the project's non-negotiable requirement is that Markdown remains the source of truth while SQLite acts only as an index and state layer; a "database as source of truth" architecture would have been simpler to implement, but would have broken the human reviewability (diff-friendly, Git-versionable) that is the project's whole reason for being. The trade-off accepted in exchange is an extra freshness-validation layer (indexed_files, mtime + sha256) to avoid serving out-of-sync content.

graph TB    subgraph Clients["MCP Clients"]        CC[Claude Code]        VS[VSCode]        OC[OpenCode]        KC[Kimi CLI]    end
    subgraph Meridian["Axiom Meridian (Python / FastMCP)"]        SRV["server.py<br/>tool registration + security pattern"]        subgraph Tools["tools/"]            KM[knowledge_management]            KCO[knowledge_consumption]            AF[audit_flows]            EX[extraction]            KT[knowledge_templates]        end        subgraph Parsers["parsers/"]            AP[atomic_parser]            LP[legacy_parser]        end        subgraph RAGL["rag/ (optional)"]            EMB[embedder]            VEC[vector_store]        end        DBC["db/ (schema, migrations, connection)"]        SEC["utils/security.py<br/>access levels"]        SR["utils/scope_resolver.py"]        RI["utils/read_index.py<br/>write_block + freshness"]    end
    subgraph Storage["Storage (KNOWLEDGE_BASE_PATH)"]        MD["Markdown files<br/>knowledge-base/*.md, lessons/*.md<br/>(source of truth)"]        SQLITE[("SQLite<br/>meridian.db<br/>(index + state)")]        CHROMA[("ChromaDB<br/>(optional vector store)")]    end
    CC & VS & OC & KC -->|MCP stdio / HTTP-SSE| SRV    SRV --> SEC    SRV --> Tools    KM --> AP    KM --> LP    KM --> RI    KCO --> SR    KCO --> RAGL    RAGL --> CHROMA    RI --> MD    RI --> SQLITE    Tools --> DBC    DBC --> SQLITE

(Diagram inferred directly from the reference implementation's source code — src/meridian/ — and previously documented in docs/03-system-architecture.md.)

2.2. Description of main components:

2.3. High-level project description and file structure

Note: this repository (axiom-meridian-project) is the capstone's documentation deliverable and hosts docs/, openspec/, and prompts/. The source-code structure shown below corresponds to the server's reference implementation (working checkout axiom-meridian/), which evolves in parallel to this documentation and is what the already-delivered tickets (section 6) build on.

axiom-meridian/├── src/meridian/│   ├── server.py              # MCP tool registration + security pattern│   ├── config.py              # Configuration loading (env vars, paths)│   ├── db/│   │   ├── schema.sql          # Full schema + seed scopes│   │   ├── migrations.py       # Versioned migration runner│   │   ├── migrations/         # NNN_*.sql files│   │   └── connection.py       # SQLite WAL-mode connections│   ├── parsers/│   │   ├── atomic_parser.py    # Canonical RN-*/LL-* format parser│   │   └── legacy_parser.py    # Free-form file parser (migration)│   ├── rag/│   │   ├── embedder.py         # Lazy loading of BAAI/bge-small-en-v1.5│   │   └── vector_store.py     # ChromaDB collection wrapper│   ├── tools/│   │   ├── knowledge_management.py    # Indexing, proposals, promotion│   │   ├── knowledge_consumption.py   # Queries, context, timeline│   │   ├── audit_flows.py             # audit_pr, check_feature_against_rules│   │   ├── extraction.py              # Transcript extraction│   │   └── knowledge_templates.py     # Canonical block templates│   └── utils/│       ├── security.py         # Access levels (read/analyze/write)│       ├── scope_resolver.py   # Scope hierarchy resolution│       ├── read_index.py       # write_block + freshness validation│       ├── id_generator.py     # Atomic IDs via id_counters│       ├── privacy.py          # Redaction of <private> tags│       ├── serializers.py      # JSON/TOON serialization│       └── skill_generator.py  # .claude/skills/ generation├── tests/│   ├── unit/                  # Parsers, resolver, migrations, security...│   ├── integration/           # Full flows (index+query, proposals...)│   ├── contract/              # MCP tool signatures│   └── benchmarks/            # Performance regression guards├── scripts/│   ├── install.sh             # Linux/macOS installer│   └── uninstall.sh└── pyproject.toml

In this repository (axiom-meridian-project), the structure reflects its documentation-first nature:

axiom-meridian-project/├── docs/                      # Baseline documentation (charter, architecture, data model...)├── openspec/│   ├── specs/                 # Baseline of already-delivered capabilities│   └── changes/                # Active change proposals (backlog)├── prompts/                   # Project working prompts└── README.md

2.4. Infrastructure and deployment

Meridian requires no cloud infrastructure: it is a local process invoked by the MCP client (stdio) or, optionally, an HTTP/SSE server bound exclusively to 127.0.0.1 (meridian serve <port>), never 0.0.0.0. In HTTP mode a random session token is emitted at startup, required as Authorization: Bearer <token> on every request; the token is never persisted and rotates on every restart.

There is no documented deployment/CI pipeline in this repository yet — the current "deployment" is the local install via scripts/install.sh described in section 1.4. Hardening a networked deployment (multi-client, TLS, rate limiting) is identified as future work in TICKET-015.

2.5. Security

• A higher level includes all lower levels.
• An insufficient level returns a structured ACCESS_DENIED error naming the required level.
• Every call — granted or denied — is recorded in access_log, excluding sensitive parameters (pr_diff, feedback_text, text, proposed_text, new_text).
• <private> tags are stripped from all inbound text before persistence, on every write path.
• The HTTP/SSE transport is bound to 127.0.0.1 by design and requires a bearer token (see 2.4).

2.6. Tests

The reference implementation's test suite follows a four-level pyramid, run with pytest / pytest-asyncio:

• Unit (tests/unit/) — parsers (atomic_parser, legacy_parser), scope_resolver, id_generator, migrations, security, serializers, connection, among others. Validate each module in isolation.
• Integration (tests/integration/) — full end-to-end flows: index + query, proposal lifecycle, access control, RAG queries, skill generation, external file edits.
• Contract (tests/contract/) — verifies that the exposed MCP tool signatures don't change in a backwards-incompatible way.
• Benchmarks (tests/benchmarks/) — performance regression guards; excluded from the default run (addopts = "-m 'not benchmark'" in pyproject.toml) and invoked explicitly with -m benchmark.

Every relevant bug fix (see ADR-003 through ADR-006 in System Architecture) added its own regression test before closing, and the delivered tickets (section 6) reference the specific test file covering their acceptance criteria.

3. Data Model

3.1. Data model diagram:

erDiagram    SCOPES ||--o{ SCOPES : "parent_id"    SCOPES ||--o{ SCOPE_ATTRIBUTES : has    SCOPES ||--o{ RULES : scopes    SCOPES ||--o{ LESSONS : scopes    SCOPES ||--o{ PENDING_PROPOSALS : "suggested for"
    RULES ||--o{ RULE_ATTRIBUTES : has    RULES ||--o{ RULE_HISTORY : has    RULES ||--o{ RULE_TAGS : has    RULES ||--o{ RULE_LESSON_LINKS : links    LESSONS ||--o{ LESSON_HISTORY : has    LESSONS ||--o{ LESSON_TAGS : has    LESSONS ||--o{ RULE_LESSON_LINKS : links    RULES }o--|| LESSONS : originated_from
    SCOPES {        text id PK        text type        text name        text parent_id FK    }    SCOPE_ATTRIBUTES {        text scope_id FK        text key        text value    }    RULES {        text id PK        text scope_id FK        text code UK        text text        text category        text severity        text applies_to        text status        text file_path        integer file_offset        integer byte_length        text originated_lesson_id FK        text embedding_id    }    RULE_ATTRIBUTES {        text rule_id FK        text key        text value    }    RULE_HISTORY {        text id PK        text rule_id FK        text change_type        text previous_text        text new_text        text reason        text triggered_by        text changed_at    }    RULE_TAGS {        text rule_id FK        text tag    }    LESSONS {        text id PK        text scope_id FK        text code UK        text project        text date_occurred        text severity        text area_affected        text what_happened        text impact        text root_cause        text resolution        text originated_rule_id FK        text status        text file_path    }    LESSON_HISTORY {        text id PK        text lesson_id FK        text change_type        text previous_text        text new_text        text reason        text changed_at    }    LESSON_TAGS {        text lesson_id FK        text tag    }    RULE_LESSON_LINKS {        text rule_id FK        text lesson_id FK        text link_type    }    PENDING_PROPOSALS {        text id PK        text type        text scope_id FK        text target_id        text proposed_text        text metadata        text status        text legacy_original        text created_at    }    PROJECT_SCOPE_RESOLUTION {        text project_id PK        text resolved_scopes        text updated_at    }    PR_AUDITS {        text id PK        text project_id        text pr_ref        text diff_hash        integer rules_evaluated        text violations_found        text audited_at    }    PLANNING_CHECKS {        text id PK        text project_id        text feature_description        text conflicts_found        text checked_at    }    ACCESS_LOG {        text id PK        text timestamp        text tool_name        text access_level        text project_id        text parameters        text result        text transport    }    ID_COUNTERS {        text name PK        integer next    }    INDEXED_FILES {        text file_path PK        real mtime        text content_hash        text updated_at    }

(ERD verified against the real schema in src/meridian/db/schema.sql of the reference implementation — 17 tables, 1:1 match.)

3.2. Description of main entities:

Extended detail, including the atomic block format and the ID-generation strategy, in docs/04-data-model.md.

4. API Specification

Meridian does not expose a conventional REST API: it exposes a set of typed MCP tools (25+ in the reference implementation — query_rules, audit_pr, create_pending_proposal, etc.), invoked through the MCP protocol (stdio or HTTP/SSE) rather than HTTP routes with verbs. Forcing an OpenAPI 3 specification onto this interface would be misleading: OpenAPI models resources and HTTP verbs, whereas an MCP tool is a function with an input/output schema (JSON Schema) and a "an action a model can invoke" semantics — closer to a function signature than to an endpoint.

As a formal alternative, this project will adopt a Semantic Tool Definition via Declarative Schema, or Model-Oriented Documentation: one document per tool specifying, in JSON Schema, its input parameters, the required access level (read/analyze/write), the response shape, and invocation examples — the same kind of contract already validated by tests/contract/test_mcp_tool_signatures.py in the reference implementation, but exposed as product documentation rather than only as a test. This convention has been identified but is not yet implemented in the project's documentation; it will be addressed in a later delivery, documenting at minimum the three most-used tools (query_rules, audit_pr, create_pending_proposal/approve_proposal).

5. User Stories

Full catalog (8 epics, As a / I want / so that format, MoSCoW priority) in docs/05-user-stories.md. Below, 3 representative ones:

User Story 1 — US-A1 — Query relevant rules for my project (Epic A, priority Must, tool query_rules).

User Story 2 — US-B3 — Review and approve a proposal (Epic B, priority Must, tools list_pending_proposals / approve_proposal / reject_proposal).

User Story 3 — US-C1 — Audit a pull request against known rules (Epic C, priority Must, tool audit_pr).

6. Work Tickets

Full catalog (delivered + backlog, traced to OpenSpec) in docs/06-work-tickets.md. Below, one backend, one database, and one frontend ticket:

Ticket 1 (Backend) — TICKET-001 — MCP server scaffold and core tool surface. Stands up the FastMCP server, the server.py security pattern, the SQLite schema, and the initial tool set. Status: Done.

Ticket 2 (Database) — TICKET-008 — Indexed read path with per-file freshness (ADR-005). Adds indexed_files, rule_tags, lesson_tags; introduces write_block as the single write choke point; moves detail="full" reads to SQLite validated by per-file freshness. Status: Done.

Ticket 3 (Frontend) — TICKET-017 — Read-only observability dashboard, corresponding to US-H1. A read-only web dashboard (server health, scope hierarchy, pending proposals, embedding projector) as a separate local process, reusing knowledge_consumption as a library. Status: Backlog — this is the only frontend component contemplated in the project; its formal specification lives in openspec/changes/add-observability-dashboard/.

7. Pull Requests

Only Pull Requests that close a complete, verifiable deliverable are referenced here. The first valid deliverable is the baseline technical documentation (project fact sheet, description, architecture, data model, user stories, work tickets) — this very README and docs/.

Pull Request 1 — #1 — Removing duplicates (merged). Cleanup of duplicated content in the baseline documentation prior to this delivery.

Pull Request 2 — Pending. Will be referenced once a PR contains the full first delivery: "Technical documentation: project fact sheet, description, architecture, data model, user stories, work tickets."

Pull Request 3 — Pending.

License

Axiom Meridian is licensed under the Apache License, Version 2.0. See NOTICE for attribution.

The names "Axiom Meridian" and "Axiom JUMA" and their marks are not licensed under the Apache License (section 6, Trademarks). Using them requires the owner's permission.

License transition: versions made available before the change to Apache 2.0 were declared under the MIT License, and copies obtained under those terms remain available under them.

Third-party: the .claude/skills/openspec-* skills are generated by OpenSpec and keep their own MIT license.

Contributions are welcome under the Apache License 2.0 with a DCO sign-off; see CONTRIBUTING.md.