Entity.md
An open, provenance-first format for agent-legible customer profiles — plus a reference implementation.
The trustworthy context layer for AI sales & marketing agents: every fact traced to its source, every change auditable.
Entity.md represents each business entity — a person, an organization, an opportunity — as a single human- and LLM-legible Markdown file (the profile), materialized from an immutable, append-only log of raw updates drawn from many sources (email, CRM, enrichment vendors, calendars, call recorders, notes). The profile is a projection; the log is the source of truth. On top of the profiles, asynchronous jobs build a typed entity graph (for GraphRAG) and a columnar analytics table (for segmentation, ICP/LTV/ACV, and predictive/prescriptive workloads).
Terminology, used consistently throughout: the entity is the resolved real-world thing (Jane Rivera; Acme Analytics) with a stable ID; the profile is the Markdown document about that entity — a rebuildable projection. They are deliberately not interchangeable: you can delete and regenerate a profile; you cannot delete an entity by deleting its file. See SPEC.md §1.1.
Entity.md is a strict superset of Google's Open Knowledge Format (OKF) v0.1. Every Entity.md entity file is a valid OKF Concept, so it interoperates with the OKF ecosystem out of the box. What Entity.md adds is the part OKF explicitly leaves out and that CRM genuinely needs: cross-source entity resolution, a bitemporal provenance ledger, declarative survivorship, a governed ontology, and an analytics projection.
ℹ️ Naming note. This project was renamed from the original Profile.md (which collided with live healthcare brands and read as "Medical Doctor") to Entity.md — a descriptive *.md convention name. Note "Entity" is generic (Entity Framework, ECS, …), so it works as a format/spec name but is not a defensible trademark; clear a distinct brand before commercializing — see docs/naming.md.
Why this exists
Most "AI + CRM" stacks feed an agent raw records via MCP and make the agent stitch identity, pick the freshest value, and reconcile conflicts at read time — expensively, non-deterministically, and with no memory. RAG re-derives knowledge on every query; nothing compounds. And when an agent writes back to a record, no CRM can answer the question that suddenly matters: which source said this, when, and what did it used to be?
Entity.md's bet, following Karpathy's "LLM Wiki": compile context once into a maintained, interlinked artifact, keep it current, and make provenance a first-class, visible feature. The Markdown file is the trust surface; the discipline underneath is what makes it a system of record rather than a folder of notes.
How this differs from prior art (read this first)
This space is crowded, and honesty is the point. Entity.md is not a new Markdown format or the first "Markdown CRM."
| Prior work |
What it does |
What Entity.md adds |
| Karpathy LLM Wiki |
The raw→wiki→schema pattern |
A CRM-specific instance with a real data spine |
| OKF v0.1 |
The Markdown+frontmatter interchange format |
Provenance, versioning, resolution, typed edges, analytics (all OKF non-goals) |
Aakeeo llm-wiki-crm |
Markdown-file CRM, mutated in place |
Immutable log-as-source-of-truth; profile is a pure projection |
| brain.md |
compiled_truth + append-only timeline for code |
Same split, for resolved CRM entities, bitemporal + queryable |
| Basic Memory |
Markdown + typed relations + MCP |
Cross-source entity resolution + provenance + analytics |
| Graphiti / Zep |
Bitemporal knowledge-graph agent memory |
Human-legible, git-native, OKF-interoperable surface |
A full, cited review — including where the design is wrong and how to fix it — is in docs/research-and-design-review.md. Start there.
Architecture
SOURCES Gmail · CRM · vendors · calendars · call recorders · notes
│ CDC: idempotent, ordered, deduped
▼
L0 RAW EVENT LOG append-only · immutable · BITEMPORAL
│ (source, assertion_type, valid_time, tx_time, confidence, payload)
▼
L1 IDENTITY RESOLUTION deterministic keys + probabilistic clustering → stable entity IDs
│ (reversible merge / split)
▼
L2 MATERIALIZED PROFILE golden record via DECLARATIVE survivorship
│ (the .md) → rendered as an OKF-conformant Markdown file ← the trust surface
├───────────────┐
▼ ▼
L3 TYPED GRAPH L4 COLUMNAR GOLD
governed compacted DuckDB / Iceberg table (NOT per-entity files)
ontology + → segmentation · ICP / LTV / ACV
Leiden → → predictive (best-time-to-reach) · prescriptive (MIP scheduling)
GraphRAG
Two rules make the whole thing sound:
- The profile
.md is a pure projection. Human and LLM edits are high-priority events in the log, never in-place file mutations. You must always be able to delete every profile and rebuild it from L0.
- Analytics never scans per-entity files. L4 is a single compacted columnar table; per-entity
.md files are the serving layer for humans and agents only.
Repository layout
.
├── README.md ← you are here
├── SPEC.md ← the Entity.md v0.1 specification (OKF superset)
├── CLAUDE.md ← the agent "schema": how an LLM maintains profiles
├── AGENTS.md ← pointer for Codex/other agents
├── docs/
│ ├── research-and-design-review.md ← the deep, cited review (read first)
│ ├── landscape-deep-dive.md ← the 4 prior projects compared + traction
│ ├── markdown-crm-tradeoffs.md ← is a markdown CRM a good idea?
│ ├── data-integration.md ← the multi-source / data-lake thesis
│ ├── faq-concepts.md ← survivorship, bitemporal, columnar, OKF
│ ├── use-cases.md ← retrieval, lookalikes, next-best-action + more
│ ├── architecture.md
│ ├── provenance-and-versioning.md
│ ├── entity-resolution.md
│ ├── ontology-and-graph.md
│ ├── analytics.md
│ ├── retrieval.md
│ ├── okf-interop.md
│ ├── security-and-privacy.md
│ ├── prior-art-comparison.md
│ └── naming.md
├── schema/
│ ├── profile.frontmatter.schema.json
│ ├── record.schema.json
│ ├── edge.schema.json
│ └── ontology.seed.yaml
├── examples/ ← a worked mini-tenant (people, orgs, deals, raw log)
│ ├── index.md · log.md
│ ├── people/ · organizations/ · opportunities/ · industries/
│ └── _raw/
├── reference/ ← runnable Python reference implementation
│ └── entitymd/ (records · resolve · materialize · graph · analytics · lint · cli)
└── .github/workflows/ci.yml
Quickstart (reference implementation)
The reference implementation is intentionally small and dependency-light. It demonstrates the spine, not a product: append raw events → resolve → materialize a profile via declarative survivorship → lint → export a DuckDB/Parquet analytics table.
cd reference
python -m pip install -e . # or: pip install -e '.[analytics]'
entitymd materialize ../examples # rebuild every profile from the raw log
entitymd lint ../examples # health-check (drift, orphans, schema)
entitymd analytics ../examples -o /tmp/gold.parquet # columnar projection (needs duckdb)
Every profile in examples/ is regenerated from examples/_raw/ — deleting the .md files and re-running materialize reproduces them exactly. That property is the spec.
Status
v0.1 — draft spec + reference implementation. Not production software. See ROADMAP.md. Feedback, issues, and PRs welcome — see CONTRIBUTING.md.
License
Apache-2.0 — matching the permissive, interop-friendly ethos of OKF, brain.md, and AGENTS.md.