Core concepts
Five ideas carry the whole product: typed memories, the folder tree, the approval lifecycle, the three-dimensional access algebra, and cited answers. Everything else — connectors, MCP, agents, the API — is a surface over these.
Memories, not pages
The unit of knowledge is a memory — a typed, versioned object, not a free-form wiki page. Each memory has a kind with its own frontmatter schema:
| Kind | What it holds | Typical origin |
|---|---|---|
| prompt | A prompt that worked, with the model used and why it worked | Pasted from ChatGPT/Claude, captured via omnibar or MCP |
| workflow | A repeatable multi-step process | Written up, or auto-captured from a successful task run |
| decision | What was decided, the reasoning, the owner, the outcome | Meeting outcomes, closed tickets |
| lesson | Something learned the hard way | Incident write-ups, merged PRs, retro notes |
| agent | An agent's prompt/config — versioned and approvable like any memory | Agent registry (see Agents) |
| doc | Reference documents and policies | Uploads, connector syncs |
Every memory is versioned append-only: each edit — human or AI — creates a new version and a new stored body; nothing is destructively overwritten. History, word-level diffs, and rollback come for free. Alongside the body, a memory carries context (the problem, why it worked, the model used, the result) and provenance — links back to the raw captures it was compiled from, with original bytes retained for audit.
The org tree
Memory lives in a folder tree materialized as paths: /company/policies, /departments/engineering/runbooks, /projects/apollo. Departments, teams, and projects are just folders — the same tree you see as the canvas in the control plane.
The tree is doing double duty, and this is the part worth internalizing:
- It's the information architecture — where things live, what the Gardener browses when filing captures.
- It's the permission model — access grants attach to folders and cover their subtree. A folder flagged
restrictedis a boundary: grants from above do not flow in.
The lifecycle: draft → reviewed → approved → deprecated
Every version sits in one of four statuses:
| Status | Meaning | Who can set it |
|---|---|---|
| draft | Unvetted; visible but labeled | Automatic on create |
| reviewed | A peer checked it | Contributor+ on the folder |
| approved | Safe to reuse — the trusted corpus | Manager on the folder only |
| deprecated | Do not reuse; kept for history | Manager, or staleness auto-flag |
Anything written by AI enters at draft. No exception, no configuration flag. It's enforced at three layers — the agents' write tools can't set status, the service layer asserts it, and a database check constraint backs both. AI can contribute to organizational memory, but only humans decide what the organization trusts. (The one honest carve-out: an admin may mark a trusted corpus import to arrive as approved — the approver is that admin, recorded as such. A human still approved it.)
Downstream, status matters everywhere: search shows status badges and offers an approved-only toggle, answers prefer approved content when sources conflict, deprecated versions never appear in search, and the recommendation agent labels anything non-approved it suggests.
The access model: three orthogonal dimensions
Access = path scope ∧ classification clearance ∧ role capability. One pure algebra, shared between in-memory checks and SQL filters.
1. Path scopes — where
Grants are additive: principal × folder × role, covering the folder's subtree. Restricted folders block inheritance — access requires a grant at or below them. New workspaces default to all members → contributor @ root.
2. Classification — how sensitive
Every memory carries a classification — public < internal < confidential < restricted — and every caller carries a clearance ceiling. A node is visible only if both the path and the clearance check pass. Paths express departmental boundaries; classification expresses sensitivity orthogonal to department. Salary bands live in the HR folder and are confidential.
3. Role capability — what you can do
| Capability | viewer | contributor | manager |
|---|---|---|---|
| Read, search, get answers | ✓ | ✓ | ✓ |
| Capture into a folder, edit (new draft) | ✓ | ✓ | |
| Approve / deprecate versions, manage grants | ✓ |
The load-bearing rule: every read surface filters by resolved scope inside the SQL query. Search (both the vector and full-text legs), the tree, answer-context assembly, and every agent tool embed the caller's scope in the query itself — unreadable content never influences ranking, snippets, or even gap signals. Post-filtering in application code is forbidden by design rule.
Cited answers and honest refusals
Ask Engram a question and the answer is assembled only from permission-trimmed context, with every claim citing the memory it came from — title, kind, status badge, path, deep link. A confidence label is derived, not model-claimed: grounded (every sentence cited), partial (weak retrieval), or no_answer.
When nothing accessible covers the question, Engram refuses explicitly — “I don't have accessible information about that” — rather than letting the model free-associate. The refusal is a feature twice over: it's what makes permission guarantees crisp (ask for salary bands without clearance → refusal, not hallucination), and every refusal is logged as a signal for gap detection — clusters of unanswerable queries become a documentation backlog.
The Gardener
Capture in Engram is deliberately dumb and fast: throw anything at it — a pasted prompt, a Slack thread, a PDF, a screenshot, a voice memo — and it returns immediately. The Gardener, an agentic compiler, then does the smart work asynchronously: classifies the kind, searches for related memory, merges into an existing node or creates a new one (contradictions with approved memory get flagged for review, never silently overwritten), writes structured frontmatter, carries provenance, and embeds for search.
The Gardener is fenced like everyone else: it can only read and write within the capturing caller's scopes, its writes always land as drafts, and captured content is treated as data, never instructions — a prompt-injection attempt inside captured text has no tool-level authority because the SQL fence doesn't care what the prompt says.