Skip to content
aizkaizk

References and lineage

aizk is a mix of published memory mechanisms, open source infrastructure, product comparisons, and work designed here. This page records which is which, so a reader can trace any behavior back to either a paper or a deliberate choice. A citation on this page does not mean aizk copied its code, and it does not mean the cited project endorses aizk. Every code path named here was checked against the tree.

How to read the map

Section titled “How to read the map”
  published work ──adopted, follows the design closely──▶ implemented mechanism
  published work ──adapted, idea kept, shape changed────▶ implemented mechanism
  published work ┄┄compared, no code┄┄▶ product boundary
  published work ┄┄workflow, no runtime┄┄▶ how we change the code
  designed for aizk ──original──▶ implemented mechanism
Label Meaning
adopted the implemented mechanism follows the cited design closely
adapted the source supplied the idea and aizk changed its shape
compared the source helped define a product boundary but supplied no code
workflow the source influenced how the code is changed or checked
original the mechanism was designed for aizk and is not claimed from the cited systems

Memory and retrieval

Section titled “Memory and retrieval”
Feature Lineage What aizk does Code
temporal entity and fact graph adopted from Zep and Graphiti immutable content plus valid-time and recorded-time claims store/models/tables/, store/models/views/live_fact.py
add, update, no-op consolidation adapted from Mem0 rules settle the confident cases and only ambiguity reaches the LLM graph/consolidation.py, graph/writer.py
associative multi-hop find adapted from HippoRAG 2 personalized PageRank inside the SQL statement, over visible current facts only retrieval/lanes/facts.py
community summaries adapted from GraphRAG and LightRAG communities as a rebuildable global-evidence projection graph/communities.py, retrieval/lanes/vector.py
recursive summary tree adopted from RAPTOR grounded summaries rolled into bounded higher levels graph/raptor.py, retrieval/lanes/overview.py
reflective observations adapted from A-MEM optional observations that never replace their grounding facts graph/insight.py
entity profiles adapted from GAM one evidence-grounded profile per entity and scope set graph/profiles.py
raw evidence as authority supported by Does Memory Need Graphs source chunks stay primary and each graph lane earns its cost in ablation retrieval/lanes/sources.py, eval/plans.py
append-only corrective history supported by APEX-MEM contradicted knowledge has its range closed rather than being deleted store/models/tables/fact.py
speaker-aware group memory adapted from GroupMemBench and Hindsight objective state kept apart from observations, opinions, experiences, preferences provenance.py, graph/grounding.py, eval/groupmem.py
forgetting-aware evaluation adopted from Memora scores current evidence without rewarding expired memory eval/metrics.py
workflow and premise categories planned from LongMemEval-V2 kept in evaluation until a production schema earns them eval/
action-memory boundary compared with Mem2ActBench no action-selection claim is made from a retrieval-only score External benchmarks
dense and lexical fusion adapted from Reciprocal Rank Fusion typed lane ranks fused inside one SQL find program retrieval/find/program.py, retrieval/lanes/sources.py
merit ordering and maximal find original every lane stays available and one cross-encoder ranks the candidates together retrieval/find/orchestrator.py, retrieval/rerank/rescore.py
public evidence provenance original internal lanes collapse into source, derived, and session evidence with exact scope descriptions retrieval/models/result.py, retrieval/templates/find.md.j2

Paths in that table are relative to src/. RAPTOR supports hierarchical summaries, GraphRAG supports community summaries, HippoRAG supports associative graph retrieval, and GAM and A-MEM support consolidated representations. None of them argues that the agent on the other side of the API should ever see a lane name. The three public provenance classes are an interface choice made here, based on what a consumer needs to judge evidence rather than on how the engine found it.

Sharing and identity

Section titled “Sharing and identity”

The split between private and shared memory is informed by Collaborative Memory. aizk turns that paper’s policy graph into one SQL-native scope lattice, where every row carries a sorted nonempty set of scope UUIDs and a reader has to stand in every member. Scope sets in depth has the mechanics.

The intersection model, full-authority reads with one explicit write destination, and the source-preserving share operation are original. Logto stays authoritative for users, organizations, roles, and public organization metadata, and aizk derives stable IDs from verified token claims without storing an identity or membership mirror at all.

Concern Source The aizk boundary
identity and organization authority Logto OIDC discovery, signed tokens, current org roles, no local identity tables
OAuth protected MCP FastMCP protected-resource metadata and direct JWT verification against Logto
database authorization CockroachDB and PostgreSQL row security with the house rlsalchemy package forced policies on both content and scoped claims
multi-user memory model Collaborative Memory private, organization, and intersection scopes with immutable capture provenance

Infrastructure and model lanes

Section titled “Infrastructure and model lanes”
Responsibility Project Use in aizk
relational, temporal, vector, and policy execution CockroachDB and PostgreSQL two adapters over one durable memory model
vector index CockroachDB C-SPANN, VectorChord and pgvector scoped native vector search for each database profile
ORM and validation SQLModel, SQLAlchemy, Pydantic typed models, PostgreSQL statements, and wire contracts
durable jobs PgQueuer and the AIZK portable queue backend-specific workers with job state in the same SQL database as memory
document conversion Docling and Docling Serve private conversion of accepted bytes into structured JSON and normalized Markdown
immutable object bytes Amazon S3, SeaweedFS and obstore private object storage behind opaque keys
malware scanning ClamAV fail-closed streaming scan before any object is persisted
log collection, storage, inspection Grafana Alloy, Loki, Grafana labeled Docker logs, one bounded store, a loopback-only viewer
log event vocabulary OpenTelemetry Logs Data Model structured events while PostgreSQL stays the durable usage authority
MCP transport and OAuth FastMCP the public tools and the Logto OIDC proxy
browser application SvelteKit and @logto/sveltekit the optional web interface over the browser JSON API
model serving vLLM with structured outputs replaceable OpenAI-compatible endpoints with grammar-constrained extraction
typed LLM calls and judging Pydantic AI and Pydantic Evals schema-constrained extraction and isolated evaluation
chunking Chonkie bounded prose and source windows
fast entity gate GLiNER2 a cheap GPU gate and an experimental extractor, never the production graph authority
production embedding Qwen3-VL-Embedding-2B text and image vectors through a generic client
production reranking Qwen3-Reranker-4B cross-encoder merit ordering across every lane
production extraction Gemma 4 12B grounded graph extraction through the generic LLM client
tracing and reproducible environments OpenTelemetry, uv.lock, and GitHub Actions stage timing and repeatable verification
typed patterns and SQL primitives the house patos package shared model, registry, and patos.sql column abstractions

Model names are deployment choices and not domain names in the code. Embedding, reranking, gating, and extraction each sit behind a client, so another compatible provider can take over without any part of the memory engine being renamed.

Original files and derived data

Section titled “Original files and derived data”

Several mature systems separate an authoritative original from replaceable interpretation, which is exactly the shape the artifact path takes.

Reference Useful mechanism The aizk adaptation
Paperless-ngx preserve the original, track checksums, index the derivative one original blob stays authoritative while Markdown and structured data live in PostgreSQL
Docling formats emit normalized Markdown plus a lossless structured document both derivatives are stored against the exact original revision
Unstructured elements normalize many formats into typed elements with source metadata source metadata is retained without adopting a second element store
ColPali retrieve pages visually rather than through lossy text one supplemental image vector beside authoritative Docling structure
VisRAG answer from page images authorized files stay available on demand, and find transfers no bytes
M3DocRAG combine visual and textual evidence page-level and video retrieval stay deferred until they measure better

Knowledge organization

Section titled “Knowledge organization”
Source Inherited idea The aizk adaptation
The PARA Method Projects are finite outcomes and Areas are ongoing responsibilities Areas and Projects are ontology entities rather than folders
Second Brain and Zettelkasten PARA gives action context while a Zettelkasten gives atomic durable knowledge one maintained brief per Area or Project, with atomic notes tagged into it
the project’s earlier Zettelkasten conventions #project and #area identify structure notes key-value source tags name an exact entity of any live ontology kind and imply no status or access

What is original to aizk

Section titled “What is original to aizk”

Cite the following as design done here rather than attributing it to one upstream paper.

  • Arbitrary nonempty scope sets with intersection visibility under forced database RLS.
  • Content-addressed graph content held separate from scoped bi-temporal claims.
  • Full-authority find paired with one explicit write destination.
  • A source-preserving share that creates provenance-linked copies rather than moving a row.
  • One maximal find plan whose cross-encoder orders every lane by merit.
  • A single prompt-ready MCP find string produced by a token-budget prefix.
  • Exact artifact revision resources that stay authorized by PostgreSQL and transfer no bytes during find.
  • An original-only blob model with database derivatives, metadata fallback, adaptive compression, shared physical bytes, a fail-closed scan gate, and no Redis anywhere.
  • Durable actor and scope usage accounting kept apart from expiring operational logs.
  • A health snapshot that checks schema, policy, jobs, models, scopes, graph freshness, and a real find in under five seconds.

Workflow influences

Section titled “Workflow influences”

The Bun Rust rewrite report and its original PORTING.md commit shaped how large refactors are run here and not the runtime. The reusable parts are a written mapping before a broad change, small trial cells, bounded ownership, an independent adversarial audit, errors treated as a work queue, and a test suite as the final authority. No Bun code is copied, and compiling is never taken as proof of behavior.

Next

Section titled “Next”