Skip to content

Add local CLAUDE.md to document repo context for AI agents #8

@MakiDevelop

Description

@MakiDevelop

Why

This repo has no local CLAUDE.md. When an AI coding agent (Claude Code, Cursor, etc.) opens this repo, it has no immediate context on:

  • What this repo is (6-layer deterministic knowledge pipeline, open-source distillation of a private mk-brain system)
  • Its relationship to sibling projects (independent derivative, not a fork)
  • Open-source constraints (English commit messages, no private data leakage, careful about maintainer-specific paths/credentials)
  • Integration contract (/search HTTP endpoint is stable and meant to be called by external agents/orchestrators)

Without this context, agents may:

  • Mistakenly treat it as part of a larger private stack
  • Suggest changes that break the open-source contract
  • Leak private-stack conventions into public commits

Proposed content (~50 lines)

A short CLAUDE.md covering:

  1. Repo identity — what this is, who it's for, current stage
  2. Relationship to upstream — derived from private mk-brain, but fully independent; no syncing, no shared state
  3. Open-source conventions — English commits, no personal paths in examples, no credentials, no private API keys
  4. Stability contract/search endpoint signature should not break without major version bump (external orchestrators depend on it)
  5. What NOT to add — private stack features (mem0 integration, Council Protocol, personal governance files)
  6. Lab Notes section — known failure modes and successful patterns specific to this repo

Priority

Low — repo works fine without it. File this as technical debt / onboarding improvement.

Context

Surfaced during a governance audit of mk-brain on 2026-04-05. The private stack recently introduced a four-layer decision framework and agent routing protocol; we confirmed those belong upstream and should NOT leak into this public repo. A local CLAUDE.md is the cleanest way to enforce that boundary for future AI agent sessions.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions