Getting Started with Knowledge

By the end of this guide, you'll be able to:

• Create scopes and record decisions, invariants, and rules
• Connect an AI agent to query and enforce them in real time
• Extract rules from your existing docs and code
• Check compliance in CI

1. Create Your Account

Sign up at asplenz.com/signup. Once your workspace is ready, you'll receive your admin API key. Save it — it is shown only once.

• API base URL : https://api.asplenz.com/knowledge
• Admin API key : <api_key>

You can generate additional keys from the dashboard.

2. Explore the Dashboard

Log into the dashboard at app.asplenz.com/knowledge. From there you can:

• Create scopes to organize your knowledge (e.g. Engineering, Operations, Product)
• Add entries — decisions, invariants, and rules — manually or via extraction
• Search across all entries with full-text filtering
• Check compliance by testing an intended action against your constraints

3. Your First API Calls

All API calls require the Authorization header with your API key. Start by listing your scopes to get the scope ID — you'll use it in the next calls.

List your scopes

curl https://api.asplenz.com/knowledge/v1/scopes \
  -H "Authorization: Bearer <api_key>"

Record a decision

curl -X POST https://api.asplenz.com/knowledge/v1/scopes/<scope_id>/decisions \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "Use Docker Compose for local development",
    "context": "Developers waste time setting up services manually",
    "author": "your-name",
    "author_type": "human",
    "tags": ["infrastructure", "dx"]
  }'

Check compliance

curl -X POST https://api.asplenz.com/knowledge/v1/check \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_id": "<scope_id>",
    "intended_action": "Deploy on Friday evening without review"
  }'

The response shows any conflicting invariants or rules — with IDs, severity, and whether approval can unlock the action.

4. Connect an AI Agent (MCP)

Knowledge exposes an MCP server. Any MCP-compatible agent — Claude.ai, Claude Code, or any other client — can connect using your API key. No server setup required.

• MCP server URL : https://mcp.asplenz.com/knowledge

Refer to your agent's documentation to add an MCP server. Use the URL above and set the Authorization header to Bearer <api_key>.

Try it

Once connected, your agent has access to Knowledge tools. Ask it:

> "What invariants does Engineering have?"
  → The agent calls the knowledge_list_invariants tool to list invariants in the "Engineering" scope

> "Can I push directly to main without a PR review?"
  → The agent calls the knowledge_check tool to check compliance for the intended action

> "Record a decision: we chose Playwright for E2E testing"
  → The agent calls the knowledge_create_decision tool to save the decision to the registry

5. Extract Rules from Your Documents

Upload your documents (PDF, Word, Markdown) via the dashboard or the ingestion API. Knowledge analyzes them and generates typed drafts — invariants, rules, and decisions — for your review.

curl -X POST https://api.asplenz.com/knowledge/v1/extract/stream \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_id": "<scope_id>",
    "documents": [{"content": "..."}],
    "auto_run": true
  }'

Review in the dashboard

Open the dashboard and navigate to the extraction page. Each draft shows:

• Type : invariant, rule, or decision
• Content : the extracted constraint or directive
• Source : the file and excerpt that motivated the extraction
• Confidence : confidence level (0.6 – 1.0)

Approve to publish to the registry. Reject to discard. Edit before approving if needed.

For Engineering Teams

Asplenz provides the prompts required to use Knowledge with your AI agent — for extraction, CI checks, and daily development. The following sections assume the Asplenz prompts are in place.

Get the Asplenz prompts →

Example: configuring MCP with Claude Code

If you use Claude Code, create or update .mcp.json in your project root and launch Claude from that directory:

{
  "mcpServers": {
    "knowledge": {
      "url": "https://mcp.asplenz.com/knowledge",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

6. Extract Rules from Your Codebase

Your agent reads and analyzes your source files locally and creates typed drafts in Knowledge for your review. Nothing leaves your machine.

> "Extract rules from ./docs, ./CLAUDE.md and ./src for the Engineering scope"
  → The agent reads and analyzes the files locally, then creates typed drafts in Knowledge via MCP

Scanning 23 files...
  47 chunks analyzed
  12 drafts generated (4 invariants, 5 rules, 3 decisions)
  2 duplicates skipped

7. Add Compliance Checks to CI (Optional)

Your AI agent reads the PR diff and checks it against the applicable rules and invariants in Knowledge before the PR is merged.

You can use your local AI agent or Asplenz's hosted agent — both connect to the same Knowledge API.

With your local AI agent

Your agent reads the PR diff locally and checks it against Knowledge:

> "Check the diff of this PR against Knowledge for the Engineering scope"
  → The agent calls knowledge_check for each change and reports any violations

With Asplenz remote agent

Send the PR diff to Knowledge via the API:

# .github/workflows/knowledge.yml
- name: Knowledge Compliance Check
  run: |
    curl -X POST https://api.asplenz.com/knowledge/v1/verify/diff \
      -H "Authorization: Bearer $KNOWLEDGE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "scope_id": "<scope_id>",
        "diff": "${{ steps.get_diff.outputs.diff }}"
      }'
  env:
    KNOWLEDGE_API_KEY: ${{ secrets.KNOWLEDGE_API_KEY }}

The response includes any conflicting invariants or rules, their severity, and whether an approval can unblock the action.

CI Compliance Check → for details on gating modes and implementation reports.