Architecture
Myco splits deterministic computation from LLM advisory work. Content hashes, IDs, dedup keys, and timestamps are computed in code and persisted in Postgres. LLMs suggest entities and relationships. Deterministic systems decide what becomes durable memory.
Client / Agent
↓ MCP tool call
MCP Server (tool validation + policy + RLS session context)
↓ deterministic writes + reads
Postgres 16 + pgvector (source of truth)
↑ advisory suggestions only
LLM Advisory Worker (embeddings, NER, relation proposals)
Deterministic: chunking, hashing, dedupe keys, graph link persistence, timestamps, audit, replay behavior. Advisory: embeddings, NER, relation proposals, confidence. Advisory output never bypasses deterministic validation and policy gates.
Core tables for memory semantics and provenance. Query and graph tooling read these directly under workspace scope.
Workspace isolation is enforced by Postgres Row-Level Security: every query is scoped by session context (`app.workspace_id`, `app.principal_role`) before data access. Isolation binds when Myco runs under the least-privilege `brain_app` role the agency kit ships; the default local quickstart connects as a superuser that bypasses RLS (single-workspace local use only).
Write paths enforce deterministic boundaries: `idempotency_key`, `trace_id`, and `raw_payload` capture, with `(workspace_id, idempotency_key)` unique so replays are no-ops. This enables replay safety, duplicate suppression, and post-incident audit.
Tool contracts are stable within a major version. The canonical contract lives in docs/api-reference.md.
| Tool | Params (shape) | Return (shape) |
|---|---|---|
| brain_context_pack | { query, limit?, context_token_budget?, include_*?, relational_limit? } | { chunks, entities, people, session_notes, relational_context, query_meta } |
| brain_search | { query, filters?, limit?, offset?, sort? } | { results[], total_estimated, retrieval_metadata } |
| brain_why | { hyobject_id | entity_id | people_id, limit_vc? } | { subject, vc_trail, source_proposals, ingest_info, evidence } |
| brain_neighbors | { node_id, node_kind, depth?, relation_types?, limit? } | connected nodes + edges (docs ↔ entities ↔ people) |
| brain_ingest | { mode: text|url|file, text? | url? | file_content_base64?, name?, tags? } | { hyobject_id, processing_state, name, storage_uri, message } |
| brain_propose_fact | { kind: entity|relation, …entity or relation fields, confidence? } | { proposal_id, state } |
| brain_annotate | { kind, content, session_id?, related_hyobject_id? } | { session_id, note_id } |
| brain_save_memory | { content, tags?, source_label? } | { hyobject_id, chunk_id, session_note_id } |
| brain_recall_memory | { query, agent_id?, limit?, include_entities? } | { memories: [{ hyobject_id, name, text, score }] } |
| brain_get_related | { subject_id, subject_kind, limit? } | related nodes grouped by relationship, with source provenance |
| brain_stats | { } (no required inputs) | { summary, storage, graph, review, schema, provenance, reliability, agents } |
| brain_set_mode | { mode: silent|ambient|audit } | { mode, message } (sets how proactively Myco surfaces what it knows) |
| brain_self_check | { } (no required inputs) | { working, needs_approval, problems } (pull-only health check with a fix per problem) |
Writes are deterministic, deduplicated by content hash, and traceable. Agents suggest new facts through `brain_propose_fact`, proposals do not silently become truth, and every accepted fact links back to its source, inspectable via `brain_why`.
Shipped in v1.2.0: compounding confidence, a fact’s confidence rises with independent corroboration and falls on contradiction; contradicted facts are superseded via the claims ledger, never silently overwritten (npm run test:compounding). Retrieval quality is measured, not asserted: 73.6% end-to-end QA accuracy on the complete 500-question LongMemEval oracle subset (reader gpt-4o-mini, judge gpt-4o), and on the full longmemeval_s set, keyless recall@5 of 89.2% (hybrid search) rising to 91.6% with the optional recency reranker (`brain_search reranker:'recency'`, `final = 0.7·relevance + 0.3·recency_norm`, deterministic, no API key), the harness ships in the repo.
Shipped in v1.2.0: Myco proposes new entity kinds and relationship types as it observes your data, surfaced by `brain_stats`. Promotion is manual by default; under explicit opt-in (`BRAIN_SCHEMA_AUTO_PROMOTE=1`), proposals corroborated across independent documents auto-promote with a full audit trail, and strict curation mode always wins. One principle holds throughout: no runtime DDL mutation from LLM output.
Failed ingest and advisory jobs are dead-lettered with a recorded reason instead of silently dropped, and reconciliation checks audit memory-write outcomes. Replay is safe because writes are idempotent and provenance-linked.
No lock-in architecture: Apache-2.0 open source, customer-owned Postgres, versioned SQL migrations, and data in plain Postgres tables. Data ownership and extraction paths remain under workspace control.
mycobrain-ingest takes local folders, GitHub repos, and now ChatGPT / Claude data exports (--from chatgpt-export / --from claude-export), every imported fact stays provenance-linked via brain_why.mycobrain-rest exposes search + why + /health over HTTP for non-MCP consumers: one workspace, the same RLS, no write routes, loopback by default, and only brain_ keys accepted (401 otherwise, the key is a bearer credential, not signature-verified).brain_* keys, caller-supplied workspace/agent arguments are ignored, so one agent can’t impersonate another to read its private memories; secrets are redacted in the audit table, and least-privilege RLS binds under the brain_app role (migration 20260615000050).