Skip to content

Epic: Assimilate Graphify into the AgentOS ecosystem as a knowledge-graph capability #38

@shaun0927

Description

@shaun0927

Summary

Assimilate safishamsi/graphify into the AgentOS ecosystem as a first-class knowledge-graph capability.

The repository being assimilated is Graphify. Q00/ouroboros-plugins is only the plugin-contract and reference-implementation surface used to express how that external repository becomes AgentOS-native. This issue is not about assimilating ouroboros-plugins itself, and it is not about any unrelated external repository or ecosystem.

The goal is to preserve Graphify's existing user experience while giving it AgentOS semantics:

  • declared command surface,
  • scoped permissions,
  • bounded filesystem/network behavior,
  • audit and provenance records,
  • resumable state,
  • progress reporting,
  • produced artifacts,
  • verification evidence,
  • and handoff artifacts for downstream AgentOS workflows.

This issue follows the capability-assimilation direction from #27:

Graphify upstream repository
        ↓
AgentOS plugin contract and command namespace
        ↓
Seed / Ledger / State / Provenance / Permission / Audit / Progress / Handoff
        ↓
AgentOS-native execution surface

The result should not be a thin subprocess.run("graphify ...") wrapper. The plugin must translate Graphify into the AgentOS trust, lifecycle, artifact, and handoff model.


Source repository to assimilate

Upstream repository:

Snapshot inspected:

  • Commit: 6939494b3e76ba94a52d1da6ff1e467206444f72
  • Commit date: 2026-05-18T21:57:09+01:00
  • Package: graphifyy
  • Version observed: 0.8.13
  • License: repository LICENSE file
  • CLI entrypoint: graphify = graphify.__main__:main

Observed upstream shape:

  • Canonical Graphify skill docs with multiple platform variants:
    • graphify/skill.md
    • graphify/skill-codex.md
    • graphify/skill-opencode.md
    • graphify/skill-aider.md
    • graphify/skill-copilot.md
    • graphify/skill-claw.md
    • graphify/skill-droid.md
    • graphify/skill-trae.md
    • graphify/skill-kiro.md
    • graphify/skill-vscode.md
    • graphify/skill-pi.md
    • graphify/skill-windows.md
  • Python modules for detect/extract/build/cluster/analyze/report/export/query/watch/hooks/MCP/Google Workspace/PR analysis.
  • Main pipeline documented as:
detect() → extract() → build_graph() → cluster() → analyze() → report() → export()
  • Primary artifacts:
    • graphify-out/graph.json
    • graphify-out/GRAPH_REPORT.md
    • graphify-out/graph.html
    • optional wiki / Obsidian / SVG / GraphML / Neo4j / callflow HTML outputs
  • Query operations:
    • graphify query
    • graphify path
    • graphify explain
  • Optional higher-risk integrations:
    • URL ingestion
    • Google Workspace export through gws
    • video/audio transcription
    • git hook installation
    • Neo4j push
    • MCP stdio server
    • GitHub PR dashboard helpers

Product thesis

Graphify turns a project or corpus into a durable, queryable knowledge graph. That makes it a strong candidate for AgentOS assimilation because agents can use the graph as structured context instead of repeatedly rereading raw files.

Users should keep the mental model they already have:

/graphify .
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

After assimilation, the AgentOS-facing experience should be command-addressable, permissioned, audited, and handoff-aware:

ouroboros plugin add https://github.com/<author>/ouroboros-graphify --plugin graphify-kg
ouroboros plugin trust graphify-kg --scope filesystem:read --scope filesystem:write

ooo graphify build .
ooo graphify query "what connects auth to the database?"
ooo graphify path "UserService" "DatabasePool"
ooo graphify explain "RateLimiter"
ooo graphify handoff --for auto

The exact spelling can evolve. The important property is that Graphify becomes an AgentOS-native capability: every Graphify behavior is represented as an AgentOS command, deferred command, or documented non-goal with explicit permission, risk, audit, provenance, artifact, and handoff semantics.


Core requirement

Expose Graphify's complete skill/CLI capability surface through AgentOS-native plugin commands while preserving the familiar /graphify workflow wherever safe and technically possible.

Each exposed command must define or derive:

  • command namespace and command name,
  • argument contract,
  • risk class,
  • required and optional permissions,
  • core capabilities used,
  • bounded execution semantics,
  • progress and resumability behavior,
  • audit events,
  • provenance metadata,
  • produced artifacts,
  • verification evidence,
  • and handoff artifacts for downstream AgentOS workflows.

Proposed plugin identity

Suggested plugin name:

graphify-kg

Alternative names:

graphify
knowledge-graph
agent-graphify

Recommended namespace:

graphify

This preserves Graphify's existing mental model while staying valid under the current namespace schema.

Suggested repository layout if implemented as a reference plugin in this repository:

plugins/
  graphify-kg/
    ouroboros.plugin.json
    README.md
    graphify_kg_plugin/
      __main__.py
      adapter.py
      command_catalog.py
      graph_artifacts.py
      handoff_builder.py
      provenance.py
      risk.py
      upstream.py

Suggested layout if distributed from a separate Graphify integration repository:

ouroboros-graphify/
  README.md
  plugins/
    graphify-kg/
      ouroboros.plugin.json
      README.md
      graphify_kg_plugin/
        ...
  catalog/
    index.json

Per #27, the repository URL remains the unit of distribution and plugins/graphify-kg/ remains the unit of selection. In either layout, the purpose is to bring Graphify into AgentOS through the plugin contract.


Target command inventory

The MVP should preserve Graphify's skill UX by mapping its upstream command surface into ooo graphify ... commands.

Upstream Graphify UX / CLI Proposed AgentOS command Initial risk Notes
/graphify . / graphify <path> ooo graphify build <path> write Builds graphify-out and attaches handoff/provenance.
/graphify <path> --mode deep ooo graphify build <path> --mode deep write More aggressive relationship extraction; may increase model/API usage.
graphify extract <path> ooo graphify extract <path> write Headless full extraction path; should be the implementation backbone.
/graphify <path> --update / graphify update ooo graphify update <path> write Incremental update after code changes.
/graphify <path> --cluster-only ooo graphify cluster <path> write Recompute communities/report from existing graph.
/graphify <path> --no-viz ooo graphify build <path> --no-viz write Skip HTML but still write report/JSON.
/graphify <path> --wiki ooo graphify wiki <path> write Builds agent-crawlable markdown wiki from graph.
/graphify <path> --obsidian ooo graphify obsidian <path> write Writes Obsidian vault artifacts; path-bounded.
/graphify query "..." ooo graphify query "..." read_only / write Read-only if no memory write; write if saving query evidence.
/graphify path A B ooo graphify path A B read_only Shortest-path evidence between concepts.
/graphify explain X ooo graphify explain X read_only Focused concept explanation from graph.
graphify add <url> ooo graphify ingest-url <url> write Requires network:read; should not be enabled in the local-only MVP.
graphify clone <github-url> ooo graphify clone <github-url> write Requires network and filesystem write; separate trust path.
graphify merge-graphs ooo graphify merge-graphs ... write Useful for multi-repo AgentOS context.
graphify export callflow-html ooo graphify export callflow-html write Generates architecture/call-flow artifact.
graphify tree ooo graphify tree write Emits tree HTML artifact.
graphify benchmark ooo graphify benchmark read_only / write Measures token-reduction evidence; may write report.
graphify global add/list/remove/path ooo graphify global ... read_only / write User-global graph store; requires clear boundary and trust semantics.
graphify hook install/status/uninstall ooo graphify hook ... write / destructive Mutates git hooks; should be explicitly confirmed.
graphify watch <path> ooo graphify watch <path> write Long-running process; may require lifecycle/process-management semantics.
python -m graphify.serve graph.json ooo graphify mcp serve read_only / write MCP stdio server; likely v1 after lifecycle semantics are clearer.
graphify prs ... ooo graphify prs ... read_only / write Overlaps with GitHub PR plugins; handle carefully.
platform install skills ooo graphify install-platform <platform> write Optional; writes external agent config files and should not be in the core MVP.

The MVP does not need to enable every high-risk command at once, but the epic should track the complete inventory so the UX-preservation target is explicit.


Recommended implementation phases

Phase 0 — Contract and command catalog

  • Add an explicit Graphify command catalog generated or derived from upstream CLI/skill docs.
  • Classify every command by:
    • risk: read_only, write, destructive,
    • required permissions,
    • optional permissions,
    • produced artifact types,
    • resumability behavior,
    • and handoff behavior.
  • Decide whether this repository hosts a reference skeleton only or the full plugin.
  • Document why Graphify is the external repository being assimilated into AgentOS under SSOT: UserLevel plugin authoring and capability assimilation #27.

Phase 1 — Local graph build/query MVP

Implement the safe local core:

  • ooo graphify build <path>
  • ooo graphify extract <path>
  • ooo graphify update <path>
  • ooo graphify query <question>
  • ooo graphify path <a> <b>
  • ooo graphify explain <node>
  • optional ooo graphify handoff

The MVP should require only:

  • filesystem:read
  • filesystem:write

and should use core capabilities such as:

  • ledger:write
  • state:write
  • provenance:write
  • handoff:attach
  • progress:write

Phase 2 — Artifact and handoff integration

Convert Graphify outputs into AgentOS-native artifacts:

  • artifact metadata for graph.json, GRAPH_REPORT.md, graph.html, wiki, callflow HTML, etc.;
  • SHA256 hashes and file sizes;
  • node/edge/community counts;
  • source corpus summary;
  • skipped/sensitive file summary;
  • graph build mode and backend metadata;
  • confidence semantics (EXTRACTED, INFERRED, AMBIGUOUS);
  • downstream handoff block usable by ooo auto, harnesses, and future Workflow IR / Run-Step-Artifact projections.

Phase 3 — Semantic extraction and model/API boundaries

Graphify's code extraction is local AST-based, but semantic extraction for docs/PDF/images may call model APIs depending on backend configuration.

This phase should:

  • make semantic/model-backed extraction explicit in command docs;
  • classify backend/network/API-key behavior;
  • avoid storing raw prompts, raw user content, tokens, or secrets in provenance;
  • record only bounded metadata such as backend name, model name if safe, token counts, artifact hashes, and result status;
  • decide whether semantic extraction requires network:write, network:read, shell:execute, or a more specific future permission.

Phase 4 — Optional integrations

Add higher-risk Graphify features only after the MVP proves the core assimilation path:

  • URL ingestion,
  • Google Workspace export through gws,
  • video/audio transcription,
  • git hook install/uninstall,
  • watch long-running mode,
  • MCP stdio server,
  • Neo4j push,
  • global graph store,
  • PR dashboard helpers.

Each optional integration should have explicit permission/risk/trust semantics and may justify a separate plugin or command family.


Manifest sketch

A v0.1-compatible MVP manifest could look like this:

{
  "schema_version": "0.1",
  "name": "graphify-kg",
  "version": "0.1.0",
  "description": "Assimilate Graphify knowledge-graph generation and querying into AgentOS handoff, provenance, and audit contracts.",
  "source": {
    "type": "local_path",
    "path": "plugins/graphify-kg"
  },
  "commands": [
    {
      "namespace": "graphify",
      "name": "build",
      "summary": "Build a knowledge graph for a bounded local corpus and attach an AgentOS handoff artifact.",
      "usage": "ooo graphify build <path>",
      "risk": "write",
      "requires_confirmation": false,
      "arguments": [
        {
          "name": "path",
          "type": "path",
          "required": true,
          "description": "Repo-relative or absolute corpus path to graph."
        }
      ]
    },
    {
      "namespace": "graphify",
      "name": "query",
      "summary": "Query an existing Graphify graph and return scoped evidence.",
      "usage": "ooo graphify query <question>",
      "risk": "read_only",
      "requires_confirmation": false,
      "arguments": [
        {
          "name": "question",
          "type": "string",
          "required": true,
          "description": "Natural-language graph query."
        }
      ]
    }
  ],
  "capabilities": [
    {
      "name": "ledger",
      "access": "write",
      "reason": "Record graph build/query evidence and decisions."
    },
    {
      "name": "provenance",
      "access": "write",
      "reason": "Record graph artifact paths, hashes, counts, and source corpus metadata."
    },
    {
      "name": "state",
      "access": "write",
      "reason": "Persist graph build state and latest artifact references."
    },
    {
      "name": "handoff",
      "access": "attach",
      "reason": "Attach graph report and query evidence to downstream AgentOS workflows."
    },
    {
      "name": "progress",
      "access": "write",
      "reason": "Report long graph build progress."
    }
  ],
  "permissions": [
    {
      "scope": "filesystem:read",
      "risk": "read_only",
      "required": true,
      "reason": "Read bounded local corpus files and existing graph artifacts."
    },
    {
      "scope": "filesystem:write",
      "risk": "write",
      "required": true,
      "reason": "Write graphify-out and AgentOS handoff artifacts."
    }
  ],
  "entrypoint": {
    "type": "command",
    "command": "python -m graphify_kg_plugin"
  },
  "audit": {
    "events": [
      "plugin.invoked",
      "plugin.permission_used",
      "plugin.completed",
      "plugin.failed"
    ]
  }
}

Adapter behavior requirements

The plugin entrypoint should perform a real AgentOS translation layer:

  1. Validate inputs and boundaries

    • Resolve paths safely.
    • Keep output paths bounded.
    • Respect .graphifyignore / inclusion behavior where applicable.
    • Do not allow path traversal to become unbounded file access.
  2. Invoke Graphify safely

    • Prefer stable Python APIs where possible.
    • Use CLI subprocess only behind the declared plugin entrypoint.
    • Treat missing graphifyy or optional extras as blocked/failure states, not silent partial success.
  3. Capture artifacts

    • Locate expected Graphify outputs.
    • Hash and summarize produced artifacts.
    • Avoid writing huge graph payloads directly into ledger/provenance.
  4. Emit provenance

    • Upstream repo/version/commit if known.
    • Plugin version.
    • Command and arguments.
    • Bounded target path metadata.
    • Backend/model metadata only when safe and non-secret.
    • Artifact hashes/counts.
  5. Attach handoff

    • Generate a compact handoff JSON/Markdown artifact that downstream AgentOS programs can consume.
    • Include suggested graph queries for follow-up work.
    • Include Graphify confidence semantics and report paths.
  6. Represent outcomes

    • completed when artifacts are produced and validated.
    • failed when Graphify execution fails.
    • blocked when required dependency/permission/trust is missing.
    • cancelled where long-running watch/build flows are interrupted.

Permissions and risk model

MVP permissions

filesystem:read   read local corpus and graph artifacts
filesystem:write  write graphify-out and AgentOS handoff artifacts

Likely future permissions

network:read       URL ingestion, GitHub clone, model/provider calls depending on runtime path
network:write      Neo4j push or external service writes
shell:execute      invoking external `gws`, git, ffmpeg/whisper, platform installers, hooks
mcp:call           MCP server/client integration if modeled as core capability
github:read        PR dashboard helpers if retained in this plugin

Risk guidance

  • query, path, explain: read_only if they do not write query memory.
  • build, extract, update, cluster, wiki, obsidian, tree, export: write.
  • hook install, hook uninstall: write with explicit confirmation; potentially destructive if overwriting existing hooks is possible.
  • neo4j-push: write or destructive depending on target database behavior.
  • global remove: write or destructive depending on whether it deletes user-global graph state.

Non-goals

  • Do not treat Q00/ouroboros-plugins itself as the target repository; Graphify is the assimilation target.
  • Do not frame this as integration with any repository or ecosystem other than AgentOS.
  • Do not turn Q00/ouroboros-plugins into a Graphify marketplace entry.
  • Do not bypass the AgentOS plugin firewall by instructing users to run raw /graphify prompts outside manifest/trust/audit semantics.
  • Do not add Graphify-specific branching to ooo auto.
  • Do not grant network/model/API/Google/Neo4j/GitHub/hook permissions implicitly.
  • Do not write raw API keys, raw tokens, raw prompts, or unbounded corpus content into provenance.
  • Do not require speculative manifest schema expansion before an implemented command proves the need.
  • Do not enable high-risk integrations before the local build/query path is contract-compliant.

Why this belongs under the #27 direction

Graphify is a strong proof case for capability assimilation because it is neither a simple CLI nor a pure prompt pack. It is a cross-agent skill, Python library, CLI, artifact generator, query engine, optional MCP server, and persistent project-memory layer.

Assimilating Graphify correctly would prove that an external agentic tool can enter the AgentOS ecosystem while preserving safety:

external graph capability
  + declared command surface
  + scoped filesystem/network/shell permissions
  + audit/provenance
  + bounded artifacts
  + Seed-compatible handoff
  + resumable state
  = AgentOS-native capability

This plugin should clarify how future OSS tools that produce durable agent context can become AgentOS-native without becoming unbounded shell wrappers or core features.


Acceptance criteria

  • A Graphify plugin design is added or tracked with a complete command inventory.
  • The command namespace preserves the upstream /graphify mental model, preferably as ooo graphify ....
  • Every upstream Graphify skill/CLI behavior is mapped to an AgentOS command, deferred command, or explicitly rejected command with rationale.
  • The local MVP commands are implemented or specified:
    • build
    • extract
    • update
    • query
    • path
    • explain
  • Each command has risk classification.
  • Required and optional permissions are documented.
  • Core capabilities are declared separately from external permissions.
  • The plugin produces or specifies AgentOS handoff artifacts for graph builds and graph queries.
  • Graphify artifacts are summarized by path, hash, size, and graph statistics rather than copied wholesale into provenance.
  • The plugin emits or specifies standard plugin audit events.
  • Missing dependencies and optional extras are represented as blocked/failure outcomes.
  • Semantic/model-backed extraction behavior is explicitly permissioned and documented.
  • High-risk features such as hooks, URL ingestion, Google Workspace, Neo4j push, MCP server, and global graph mutation are either deferred or guarded by explicit permissions and confirmations.
  • Documentation explains how Graphify proves the SSOT: UserLevel plugin authoring and capability assimilation #27 capability-assimilation model.
  • Tests or fixtures validate manifest compliance and command catalog coverage.

Open design questions

  1. Should the first implementation live in Q00/ouroboros-plugins as a contract-bearing reference plugin, or in a separate ouroboros-graphify repository with this repo hosting only the RFC/reference skeleton?
  2. Should graphifyy be vendored, installed as an external tool, or resolved through a plugin-local environment?
  3. Does the current manifest schema need a dependency declaration field, or can dependency checks remain runtime-blocking behavior for v0?
  4. Should query commands write memory artifacts by default, or remain strictly read-only unless --save is passed?
  5. Should graphify prs remain inside this plugin, or should it be delegated to GitHub PR plugins to avoid capability overlap?
  6. How should long-running watch and MCP server modes map to AgentOS lifecycle/process semantics?
  7. Should platform installer commands be exposed at all, given that AgentOS should be the execution surface rather than an installer for other agent harnesses?

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions