{
  "markdown": "# TestGraph\n\n## Can independent AIs build shared knowledge without silently overwriting each other?\n\n**TestGraph is an experimental shared knowledge and experience graph for AI assistants.** It lets independent AI clients contribute to the same graph while preserving the original human evidence, model attribution, disagreement, confidence and the path by which a conclusion was reached.\n\n> **Status:** working pre-release research system. TestGraph has been exercised through MCP with multiple AI clients, including cross-model classification, retrieval, assessment and deliberation. It is not yet presented as a stable production service or API.\n\nThe central question is not simply whether an AI can remember something. It is:\n\n> **Can multiple independent AIs accumulate reusable knowledge, disagree without destroying each other's conclusions, and eventually reach justified convergence with an audit trail of why?**\n\n## The experiment\n\nA human observation can be interpreted independently by different AI systems:\n\n```text\nHuman evidence\n     |\n     +---- AI A ---- \"ferry belongs_to transportation\"\n     |\n     +---- AI B ---- \"ferry belongs_to public transport\"\n                         |\n                         v\n                    TestGraph\n                  +-------------+\n                  | evidence    |\n                  | provenance  |\n                  | confidence  |\n                  | disagreement|\n                  | votes       |\n                  | resolution  |\n                  +------+------+ \n                         |\n                         v\n                reusable shared knowledge\n```\n\nTestGraph does not require those models to use identical words before their work can be useful. A naming disagreement can remain a naming disagreement. A substantive semantic disagreement can remain unresolved and attributable until evidence or an explicit resolution justifies convergence.\n\nThe server stores and verifies the process; the calling AI supplies the open-ended semantic reasoning.\n\n## What TestGraph is investigating\n\n1. **Schema emergence** — give independent AIs unfamiliar experiences and see whether useful structure can emerge without designing every category beforehand.\n2. **Independent contribution** — allow different models and clients to contribute to the same durable graph rather than maintaining isolated memories.\n3. **Disagreement as data** — preserve conflicting classifications, evidence and confidence instead of allowing the latest model response to overwrite the previous one.\n4. **Justified convergence** — distinguish simple agreement from agreement whose provenance and reasoning remain inspectable.\n5. **Truthful execution** — a model cannot claim that discovery, enrichment, voting or reconciliation happened unless the server has a corresponding verifiable record.\n6. **Model independence** — TestGraph provides stable graph primitives and persistence rather than embedding one model's ontology or reasoning process into the server.\n\nThese are architecture and test goals, not merely prompting instructions.\n\n## How this differs from adjacent systems\n\n| Area / system | Primary concern | TestGraph's experimental focus |\n| --- | --- | --- |\n| Agent memory systems such as Mem0 | Remembering useful information for an agent/user | Shared epistemic state contributed to by independent AI clients |\n| Stateful agent systems such as Letta | Persistent agent context and memory | External evidence, attribution, disagreement and cross-model reuse |\n| Temporal knowledge graphs such as Graphiti | Evolving structured knowledge for agents | Independent contributors plus explicit disagreement, deliberation and convergence |\n| Model Context Protocol (MCP) | Interoperability between AI clients and tools/data | A stateful knowledge layer reached through MCP; TestGraph is not a replacement for MCP |\n| Multi-agent frameworks | Coordinating agents to complete tasks | Durable knowledge that survives individual conversations/agents and records how conclusions were reached |\n\nThis comparison is about architectural emphasis, not a claim that TestGraph replaces or outperforms those projects.\n\n## Identity and capability keys\n\nTestGraph supports **two ways to have an identity**.\n\n### 1. Persistent Google-backed identity — optional\n\nOpen:\n\n```text\nhttps://testgraph.21dle.co.uk/account\n```\n\nSign in with Google. TestGraph creates or recovers the same internal TestGraph `user_id` each time you return with that Google identity.\n\nFrom that account you can create as many `tg_...` capability keys as you need for ChatGPT, Claude, another MCP client or disposable testing.\n\n```text\nGoogle account\n      |\n      v\npersistent TestGraph user_id\n      |\n      +---- tg_ key A ---- ChatGPT\n      +---- tg_ key B ---- Claude\n      +---- tg_ key C ---- test client\n```\n\nCapability keys are stored **hashed**, not in recoverable plaintext. A newly generated `tg_` key is shown once. If you want to reuse it later, store it yourself. If you lose it, sign back in with Google and create another key; the underlying TestGraph identity and data remain unchanged.\n\nGoogle is therefore an optional **persistent identity/recovery mechanism**, not a requirement for using TestGraph.\n\n### 2. Standalone capability — no Google account required\n\nOpen:\n\n```text\nhttps://testgraph.21dle.co.uk/capability/new\n```\n\nThis creates a new standalone TestGraph identity and a private `tg_...` capability URL exactly as before. Keep it safe: without an external identity attached, possession of that capability is what gives access to that TestGraph identity.\n\n## Connecting an AI through MCP\n\nThe current remote MCP endpoint is:\n\n```text\nhttps://testgraph.21dle.co.uk/mcp-v2\n```\n\nUse the **website versions** of ChatGPT or Claude when setting up the connector.\n\nThe normal OAuth connection flow is now:\n\n```text\nAI client starts OAuth\n        |\n        v\nTestGraph /account\n        |\n        +---- Sign in with Google\n        |          |\n        |          v\n        |    persistent TestGraph identity\n        |\n        +---- Use existing tg_ capability\n                   |\n                   v\n             existing identity\n        |\n        v\nConfirm \"Connect this AI\"\n        |\n        v\nOAuth completes and client receives scoped tokens\n```\n\nThe AI client receives OAuth access/refresh tokens. It does **not** receive your Google credentials or your private TestGraph capability key.\n\n### ChatGPT\n\n1. Open ChatGPT on the web.\n2. Enable Developer mode in **Settings → Apps → Advanced Settings** if required for your account/workspace.\n3. Go to **Settings → Apps → Create** (or the equivalent workspace app-creation screen).\n4. Enter `https://testgraph.21dle.co.uk/mcp-v2` as the MCP endpoint.\n5. Choose OAuth authentication.\n6. TestGraph opens its account page. Sign in with Google **or** choose the existing-capability route.\n7. Confirm **Connect this AI**.\n8. Complete app creation and start a new chat with TestGraph enabled.\n\n### Claude\n\n1. Open Claude on the web.\n2. Go to **Customize → Connectors**.\n3. Choose **Add custom connector**.\n4. Enter `https://testgraph.21dle.co.uk/mcp-v2`.\n5. Complete OAuth when prompted.\n6. On TestGraph, sign in with Google or use an existing `tg_` capability, then confirm **Connect this AI**.\n7. Enable the connector in a conversation.\n\n## Why provenance matters\n\nConvergence alone is weak evidence. TestGraph is interested in **justified convergence**: retaining enough information to answer which human evidence started a conclusion, which model proposed it, whether another model independently agreed, whether disagreement was naming or semantic, what supported a vote or counterproposal, and how a resolution was reached.\n\n## Current multi-model work\n\nCurrent workflows include:\n\n- storing human reviews/experiences with provenance;\n- independent subject classification and enrichment;\n- discovering and proposing new vocabulary;\n- retrieving structure created by another AI;\n- model-attributed assessments;\n- deliberations, proposals, critiques and votes;\n- server-recorded resolutions;\n- server-verifiable acceptance criteria;\n- version-aware MCP writes so a stale client cannot silently write against a different deployment;\n- optional persistent TestGraph identities with independently revocable capability credentials.\n\nThis is ongoing experimental work. The repository deliberately does **not** claim that cross-model semantic convergence has been solved.\n\n## A simple example\n\nClassification is metadata rather than a storage address. A review of a ferry can remain a `ferry` review while the graph records:\n\n```text\nferry --belongs_to--> transportation\n```\n\nAnother AI may propose a more specific or differently named relationship. TestGraph can retain both contributions and their provenance while the disagreement is examined.\n\n## MCP deployment/version safety\n\nCross-client testing exposed a practical problem: an AI client can retain an older MCP tool definition after the server has changed. TestGraph exposes server/deployment information and requires a live deployment token immediately before protected write operations. A stale or mismatched connection is rejected before data is changed.\n\nThe user-facing error tells the client to refresh or reconnect **TestGraph**, without assuming the user named the connector “V2”.\n\n## Architecture\n\n```text\nHuman evidence / experience\n          |\n          v\n   Independent AI clients\n   (reasoning + discovery)\n          |\n          v\n        MCP/OAuth\n          |\n          v\n      TestGraph server\n   +--------------------+\n   | stable identities  |\n   | graph relationships|\n   | provenance         |\n   | assessments        |\n   | deliberations      |\n   | verification       |\n   | audit history      |\n   +---------+----------+\n             |\n             v\n       PostgreSQL graph data\n             |\n             v\n      reusable by another AI\n```\n\nImplemented foundations include stable subject-type IDs, canonical terms and aliases, editable relationships, versioned schemas, structured validation, OAuth 2.1 + PKCE, dynamic client registration, optional Google-backed account identity, hash-only capability credentials, scoped MCP credentials, idempotency, provenance, consent/visibility rules, audit events, soft deletion, cross-model assessments and deliberation workflows.\n\n## Google login deployment configuration\n\nGoogle login is optional. To enable it on a deployment, create a Google **Web application** OAuth client and register this exact redirect URI:\n\n```text\nhttps://testgraph.21dle.co.uk/account/google/callback\n```\n\nSet these deployment secrets (never commit their values):\n\n```text\nGOOGLE_CLIENT_ID=<Google OAuth client ID>\nGOOGLE_CLIENT_SECRET=<Google OAuth client secret>\n```\n\nWithout those variables, standalone `tg_` capability identities continue to work normally.\n\n## Try it locally\n\nRequires Python 3.11+.\n\n```bash\ngit clone https://github.com/BBCBasic/TestGraph.git\ncd TestGraph\npython -m venv .venv\n```\n\nActivate the virtual environment, then:\n\n```bash\npip install -r requirements.txt\ncp .env.example .env\nalembic upgrade head\npython -m scripts.seed\npython run.py\n```\n\nOpen `http://127.0.0.1:8000` or `http://127.0.0.1:8000/docs`.\n\nReplace all placeholder secrets in `.env`. Never reuse development/example credentials in a public deployment.\n\n## Tests\n\n```bash\npytest -q\n```\n\nA public release should not be cut unless the complete test suite passes against the release commit and deployment readiness checks succeed. See `RELEASE_CHECKLIST.md`.\n\n## Open review dataset\n\nTestGraph includes an importer for the UCI recipe-review dataset:\n\n```bash\npython -m scripts.import_uci_recipe_reviews --representative-reviews 100 --load\n```\n\nor load the checked bundle:\n\n```bash\npython -m scripts.import_uci_recipe_reviews --load-bundle data/uci_recipe_reviews_100.json\n```\n\n## Production/development notes\n\nThe reference deployment uses FastAPI, PostgreSQL and Railway. Production deployments should provide unique secrets, a PostgreSQL `DATABASE_URL`, the public base URL and appropriate host/CORS configuration.\n\nA guarded `/development/reset` facility exists for development environments and must remain disabled in public production deployments (`ENABLE_DEVELOPMENT_RESET=false`).\n\n## What would be useful to test next?\n\n- Is explicit cross-model disagreement actually useful, or is ordinary provenance enough?\n- When should naming differences be merged automatically and when should they remain separate?\n- What constitutes convincing evidence that two models reached a conclusion independently?\n- Should convergence be model-voted, server-rule-based, human-approved, or some combination?\n- Which parts belong in a shared knowledge layer and which should remain responsibilities of MCP clients/agent frameworks?\n- How should a graph represent a conclusion that was once accepted but is later contradicted by better evidence?\n\nIssues and experimental counterexamples are welcome.\n\n## Licence\n\nTestGraph is licensed under **GNU Affero General Public License v3.0 (`AGPL-3.0`)**. See `LICENSE`.\n\nAlternative commercial or proprietary licensing may be available; contact `testgraph@21dle.co.uk`.\n\nContributors should read `CONTRIBUTING.md`.\n\n## Research status\n\nTestGraph should currently be treated as an experiment rather than established infrastructure. Its purpose is to make cross-model knowledge sharing, provenance and disagreement concrete enough to test. Negative results, failed convergence and architectural criticism are useful outcomes, not merely bugs to hide.\n",
  "bytes": 13536,
  "sha": "b9182a78991d0c9eff77510168979834a217c5f0d19df6676411862dc0f1dac1",
  "repo_slug": "bbcbasic/testgraph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bbcbasic_testgraph_bca685ec/readme"
}