Skip to content

AlexanderSmyslowski/central-agent-data-hub

BranchesTags

Repository files navigation

Agent Data Hub

reviewed context for humans and agents

Agent Data Hub is an early local-first technical preview for reviewed project memory and disciplined agent work.

License: MIT.

It is built for a simple problem: agents often work from scattered chats, partial context, and stale assumptions. Agent Data Hub gives them a smaller, reviewable starting point and gives humans a calmer way to inspect what is actually known.

What It Is

Agent Data Hub separates three things:

  • Memory: reviewed project knowledge stored in PostgreSQL.
  • Working context: the compact brief an agent starts from for one run.
  • Working rules: repo-local instructions such as AGENTS.md, skills, and project documents.

Useful signals that are not reviewed yet should stay outside the Hub in a Signal Inbox until they are triaged.

The Hub stores curated facts, decisions, risks, open questions, reports, and relations. It can export a human-readable Markdown projection and show the same state in a small local review UI called Hub View. Hub View can also accept or reject draft memory candidates as explicit, audited human review actions.

What It Is Not

Agent Data Hub is not:

  • a raw chat log store
  • a secret store
  • an autonomous schema generator
  • a hosted multi-user SaaS
  • a replacement for repo-local working rules

It is a local reviewed context system with operational checks, backups, and explicit project boundaries.

The automation boundary is intentionally conservative: checks, exports, receipts, backups, and read-only context can run automatically; triage may make suggestions; Hub writeback stays reviewed; deployments, credentials, destructive actions, and external publishing require explicit human approval.

Public Preview Status

This repository should currently be read as an early local-first technical preview.

The early milestones are defined narrowly in docs/public/v0.2-definition.md: a reliable local reviewed-context loop, not a hosted product or broad automation platform. The following milestone is docs/public/v0.3-definition.md: the local multi-agent trust loop from draft candidate to reviewed context and handoff. The next reliability milestone is docs/public/v0.4-definition.md: clear agent behavior when the local Hub is ready or offline. The first external-developer milestone is docs/public/v0.5-definition.md: registering one real local project and completing a reviewed context loop. The CLI-first bootstrap milestone is docs/public/v0.6-definition.md: registering that project through the installed agent-hub command. The release-candidate evidence milestone is docs/public/v0.7-definition.md: keeping the major public and operational loops visible as separate proofs before tagging. The runtime-health milestone is docs/public/v0.8-definition.md: making local disk, temp, Docker, port, backup, migration, status, and check signals visible before agent work depends on them. The v1.0 target is docs/public/v1.0-definition.md: boringly reliable reviewed context infrastructure for local agent work.

What is already real:

  • a PostgreSQL-backed memory model
  • start/finish wrappers for disciplined agent runs
  • quality checks, receipts, and backup verification
  • Markdown/Obsidian projection
  • a local Hub View for reading reviewed memory and reviewing drafts

What is still rough:

  • installation is currently checkout-based rather than a standalone package
  • the daily operator path still depends on repo-local shell scripts
  • the human first-run proof is required before a v1.0 tag or broader promotion

Trust Model

Agent Data Hub records reviewed project memory. A reviewed item means a human or approved local review path accepted the item with source, status, and audit metadata. It does not prove the real-world claim is objectively true, current, or complete. Review can still be wrong.

The older JSON field name verified_project_state remains part of the versioned context-pack contract for compatibility. Treat it as reviewed project state, not as an external truth guarantee. See docs/public/trust-model.md.

Architecture

flowchart TD
    Rules["Working rules\nAGENTS.md / Skills / Repo docs"]
    Signals["Signal Inbox\nunreviewed signals"]
    Triage["Triage\nreview and recommendation"]
    Context["Working context\nstart / compile / context"]
    Memory[("Reviewed memory\nPostgreSQL")]
    Views["Human views\nMarkdown / Obsidian / Hub View"]
    Checks["Checks\nquality / receipts / backups"]
    Agents["Agents"]
    Humans["Humans"]

    Agents --> Signals
    Humans --> Signals
    Signals --> Triage
    Triage --> Memory
    Rules --> Context
    Memory --> Context
    Context --> Agents
    Agents --> Checks
    Checks --> Memory
    Memory --> Views
    Views --> Humans
Loading

Public Quickstart

Requirements: Python 3.11+, Docker, and Docker Compose. Start Docker first.

For the neutral public demo, run one script:

git clone https://github.com/AlexanderSmyslowski/central-agent-data-hub.git
cd central-agent-data-hub
scripts/first_run_demo.sh

The script creates .venv if needed, installs or reuses the local CLI, creates .env from .env.example if missing, starts the isolated public demo database, runs the public demo check, then starts Hub View and prints the local URL to open. It does not overwrite an existing .env.

For this preview, the git checkout is the installation unit: clone is installation, and git pull plus pip install -e . is the upgrade path. The daily operator path still uses repo-local Bash scripts, so native Windows is not a supported target for this preview. See docs/public/installation.md.

In the first ten minutes, check only this path:

  • open the printed Hub View URL
  • open the demo project
  • review the one neutral suggested memory change in Review Inbox
  • prepare one agent handoff from the demo project
  • run scripts/db_doctor.sh --public-demo if the demo Hub appears offline

The one-command path uses demo-reviewer only for local demo attribution; this is not authentication and is not written to .env.

For a step-by-step walkthrough, see docs/public/first-run-demo-session.md.

Other first-run modes:

scripts/first_run_demo.sh --no-hub-view
scripts/first_run_demo.sh --mobile

Mobile preview is for reading and orientation on a trusted Wi-Fi or local network; Hub View disables Review Inbox and Codex setup writes when it is not bound to loopback. Direct non-loopback Hub View starts require --allow-lan-read.

Troubleshooting:

scripts/db_doctor.sh --public-demo

The broader trust-loop check runs in a separate isolated demo database:

scripts/smoke_trust_loop.sh

It creates draft candidates from a temporary signal note, verifies Review Inbox visibility, accepts one draft with the CLI and one through the public Review API, checks the audit trail, and confirms that prepare, handoff, and the read-only MCP prepare payload see the accepted items as reviewed memory.

The offline behavior check deliberately points agent wrappers at a missing test container:

scripts/smoke_agent_offline.sh

It confirms that preflight reports the Hub as offline and that agent_finish.sh prints an Offline Finish Protocol instead of implying that reviewed memory was written.

The first external-developer check runs a temporary local project through the daily-use path:

scripts/smoke_external_developer.sh

It registers a new local Git repository, installs the repo-local agent instructions, starts from reviewed context, reviews one draft, and confirms that prepare, handoff, and agent_finish.sh see the accepted item.

Hub View is a local review surface, not the operational source of truth. The interface can be switched between English and German; stored memory stays in its original language.

After The Demo: Daily Local Use

The public demo proves the shape. Daily use starts when you register a real local project, install or copy the repo-local agent rule, and run one reviewed work loop:

agent-hub register-project --repo /path/to/project --slug <project-slug> --name "Project Name"
scripts/agent_start.sh --project <project-slug> --query "<current focus>" --review
# work inside that project boundary
scripts/agent_finish.sh --project <project-slug> --review

Use Hub View as the local human workbench: inspect reviewed memory, review drafts, and prepare visible agent handoffs. Use the CLI/MCP paths for exact agent automation. See docs/public/daily-use.md for the canonical daily workflow.

Agent Workflow

Hub View can make the agent handoff visible from the UI. Open a project, use Connect an agent, enter the task, and click Prepare agent handoff. The generated view starts with Connect your agent: choose the agent you use, follow the matching setup card, then check the handoff. It shows which reviewed facts, decisions, risks, questions, reports, and trail entries would be handed to a chatbot or local agent, plus how that context should influence the work.

For chatbots, the practical path is copy and paste. For local agents, the better path is one-time connection: configure the agent to request ADH context at task start through the read-only MCP surface or an equivalent startup rule. Hub View separates setup paths for Claude Code, Codex, Hermes or custom startup rules, and generic MCP-compatible agents. Claude Code gets a single copyable setup command. Codex gets a guarded local setup action: when Hub View knows the project folder, it previews the AGENTS.md block and can install it only after an explicit local click. The copyable command remains available as a fallback. Hermes/custom agents get a startup-rule block; other MCP clients get the config shape. The same page shows Connection verification: Codex can be checked against the repo-local AGENTS.md block when the project folder is registered; other agents remain honest manual checks in their own configuration. The terminal start command remains useful as a manual fallback until the local agent is connected, not as the intended long-term daily UX.

The normal run rhythm is:

scripts/agent_start.sh --project <project-slug> --query "<current focus>" --review
# work inside one project boundary
scripts/agent_finish.sh --project <project-slug> --review

agent_start.sh prints an ADH Context Loaded receipt before the detailed memory sections. The receipt shows the project, task, reviewed-memory counts, and the same influence rules shown in Hub View.

For a task-specific read-only context pack:

agent-hub prepare --project <project-slug> --task "review release readiness"

prepare turns reviewed memory into a concrete working brief for one task. It does not write memory, import signals, or make decisions. The output includes a Context Trail that lists included source item counts, IDs, status, task scores, review status, and inclusion reasons. Drafts may appear in a separate review section, clearly marked as unconfirmed. --task ranks facts, decisions, and reports with deterministic PostgreSQL full-text search, then fills with recent reviewed context. Active risks and open questions remain on a safety floor and are not filtered out by task text.

prepare also includes a compact Known Gaps section. It can show stale items, unanswered questions, empty memory types, task blind spots, and pending drafts. These are read-only labels in the context pack. A stale reviewed item stays reviewed; there is no silent demotion, re-review, or automatic action. The default stale threshold is 42 days and can be changed with:

agent-hub prepare --project <project-slug> --task "review release" --stale-after-days 60

MCP (Read-Only)

Agent Data Hub can expose reviewed context to MCP-capable agents over stdio:

pip install -e ".[mcp]"
agent-hub mcp-serve

The MCP server is deliberately read-only. It can list projects, build the same JSON context pack as agent-hub prepare --format json, search reviewed memory, and return the compact agent-hub brief --format json shape. It cannot remember, import, accept, reject, sync, or modify memory.

For stdio MCP, the local agent normally launches agent-hub mcp-serve when it needs context. Hub View can show the setup and the context handoff, but ADH does not silently inject context into an unconfigured agent. A local agent must be configured once; after that, the agent is instructed to request ADH context at the start of each ADH-related task.

Example Claude Code setup from this checkout:

claude mcp add agent-data-hub -- agent-hub mcp-serve

Equivalent .mcp.json shape:

{
  "mcpServers": {
    "agent-data-hub": {
      "command": "agent-hub",
      "args": ["mcp-serve"]
    }
  }
}

Generic stdio clients should launch agent-hub mcp-serve with DATABASE_URL set for the local Hub database. Writes stay behind the CLI and Hub View review paths, where the human review gate is explicit.

OKF Export Preview

Agent Data Hub can export reviewed project memory as a small Open Knowledge Format preview bundle:

agent-hub export-okf --project <project-slug> --out .local/okf/<project-slug>

The OKF export is read-only and deterministic. It writes Markdown files with YAML frontmatter for reviewed facts, accepted decisions, active risks, open or answered questions, and published reports. Drafts, proposed items, archived items, rejected decisions, resolved risks, and superseded reports are excluded. This is an export target, not a second source of truth or an import/sync layer. Use a fresh output directory for preview exports. The command overwrites generated paths, but it does not remove stale files that may remain from an older bundle.

Submit only sourced, non-sensitive memory candidates:

scripts/project_remember.sh \
  --project <project-slug> \
  --type fact \
  --text "Reviewed project memory goes here." \
  --source "non-sensitive source"

The wrapper applies the same routing as the CLI. Ordinary candidates become drafts; sensitive or contradictory candidates require review first.

Drafts and Review Inbox

New memory candidates are routed before they touch reviewed memory:

  • auto: reversible evidence such as receipts, audit records, or same-source refreshes of an existing reviewed item
  • ask: money amounts, secret or credential patterns, customer-data hints, deletion intent, or contradictions with existing reviewed memory
  • draft: ordinary unreviewed candidates

Drafts are stored with status draft and remain outside reviewed memory until a human explicitly accepts them. The draft status is supported for facts, decisions, risks, open questions, and reports:

agent-hub inbox
agent-hub inbox --for alice
agent-hub inbox --accept <draft-id> --reviewer bob
agent-hub inbox --reject <draft-id> --reviewer bob

There is no time-based auto-accept and no silent promotion from draft to reviewed memory.

Draft visibility is intentionally split by surface:

  • agent-facing reads (brief, compile, handoff, context, MCP project_brief, and default search) exclude drafts and inactive memory statuses
  • search --include-drafts can show unreviewed drafts, and search --include-archived can show archived or inactive statuses
  • daily human summaries still show draft activity and include a N drafts awaiting review (agent-hub inbox) line
  • Obsidian export keeps draft pages, adds review_status: draft, and marks them as unreviewed; compiled overview pages show only the draft count and inbox pointer, not draft items in the main reviewed lists

Agent Data Hub v0.1.x uses attribution instead of access control: everyone in the trusted local workspace can see the review inbox, but every accept/reject decision must carry a reviewer handle. This is not an authentication system. Draft routing can suggest a responsible reviewer through --metadata assigned_reviewer=alice, projects.metadata.default_reviewer, or a local default, but it does not create permissions. Another reviewer can still accept the draft; the audit records both handles.

Integration Surface For External Review Adapters

External review adapters must import only agent_hub.review_api. The supported functions are:

  • connect
  • fetch_drafts
  • review_draft_by_id
  • validate_reviewer_handle
  • resolve_responsible_reviewer

Everything else in agent_hub is internal and may change without notice. Review adapters may submit only registered review_source values; ADH currently recognizes cli, hub_view, and telegram.

If something useful does not fit an existing category, record a structure question instead of forcing it into the wrong type:

scripts/project_schema_friction.sh \
  --project <project-slug> \
  --observed "This rule does not belong in durable memory." \
  --why "It may belong in AGENTS.md or a skill manifest." \
  --dry-run

Human Views

Agent Data Hub can project reviewed memory into Markdown for human reading and Obsidian graph navigation. It can also render the same project set in Hub View. Hub View includes a Workspace Overview for seeing the local Hub as a whole. It shows which projects already contain reviewed knowledge, where suggestions are waiting, which risks are visible, and which projects are still empty, demo-only, explicitly marked as personal, or not classified yet. Workspace areas come only from project metadata and visible memory counts; Hub View never infers company or private status from a project name, slug, or description. This is meant to help a maintainer understand what is already stored before adding more shared company knowledge.

Hub View is mostly read-only. Its only Hub-memory write actions are accepting or rejecting one draft at a time through the Review Inbox. It may also install the repo-local Codex AGENTS.md setup block after an explicit local click.

The human-facing surfaces are for:

  • reading
  • workspace inventory
  • explicit draft review
  • graph navigation
  • notes and handoff inspection

They are not the binding database. PostgreSQL remains the reviewed source of truth.

Signal Inbox

Not every useful input belongs in reviewed memory immediately.

Agent Data Hub now documents a small Signal Inbox pattern for:

  • X or Twitter research
  • Gmail observations
  • Hermes or Codex notes
  • external links and screenshots

The Signal Inbox is a human-readable wiki folder outside PostgreSQL. Triage decides whether a signal should be ignored, kept in the wiki, promoted to a memory candidate, or treated as a skill or policy hint.

Initialize one with:

scripts/init_signal_inbox.sh --path /path/to/wiki/inbox/signals

That initializer now creates only a minimal root by default. Add a first source file only when a real source needs one:

scripts/init_signal_inbox.sh --path /path/to/wiki/inbox/signals --scaffold-source x-research

Safety Boundaries

Do not store these in the Hub:

  • passwords
  • API keys or tokens
  • FTP credentials
  • private customer data
  • raw invoice data
  • deployment secrets
  • unreviewed claims
  • cross-project assumptions

Startup Paths

This repository now has two deliberately separate startup paths:

  • scripts/db_start_public_demo.sh: neutral public demo path
  • scripts/db_start.sh: configured local ops path

The public path is the recommended first experience for outside developers. It forces its own local demo database name, container, volume, and port (agent_hub_demo, central-agent-data-hub-demo-postgres, central-agent-data-hub-demo-pgdata, and 55434 by default), and it refuses to run if the effective target is not the demo database. DATABASE_URL in .env is intentionally ignored by that path.

The configured local ops path uses the database from .env and does not ship maintainer-specific seed data. Register your own projects with scripts/register_project.sh, or pass a private machine-local seed file explicitly with scripts/db_start.sh --seed-file /path/to/local-seed.sql. The seed boundary is documented in seed/README.md.

If the local Hub appears offline, diagnose it before restarting random pieces:

# Public demo path:
scripts/db_doctor.sh --public-demo

# Configured operator path:
agent-hub doctor

For known local Docker/Postgres stale-lock failures, the guarded recovery path is:

scripts/db_recover.sh --apply

Recovery first creates a local Docker-volume snapshot, removes only empty or NUL-only Postgres lock files, recreates the container without deleting the volume, and then runs a status check. It does not drop databases, remove volumes, or alter Hub memory rows.

Further Reading

About

Verified context for humans and agents: local reviewed memory, compact agent context, and human-readable review surfaces.

Topics

postgres developer-tools obsidian shared-memory ai-agents local-first context-management

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 21

Agent Data Hub v0.1.20 Latest
Jul 2, 2026
+ 20 releases

Packages

 
 
 

Contributors

Languages