Chat fades, code drifts, and agents guess. The contract layer now has Neo4j-first memory

Workspace Memory: A Contract Layer for AI Software Work

Repo: https://github.com/vedaterenoglu/workspace-memory

That is the short version of why I created workspace-memory.

The first version of this idea was simple: AI-assisted software work needs a place where intent does not disappear into chat, where code evidence can be checked against what humans actually approved, and where agents can get useful context without guessing.

That is still the reason for the project.

But the architecture has become clearer.

workspace-memory is not PostgreSQL-first with graph memory treated as a sidecar. It is a Neo4j-first memory and reasoning system with PostgreSQL as the ledger and operational store. Human contract files remain the reviewed truth. Neo4j stores graph knowledge, relationships, lifecycle history, search, context, impact, and code evidence. PostgreSQL records what happened: source events, document versions, ingestion runs, LLM extraction runs, graph write receipts, audit records, and reports.

That distinction matters because the project is not trying to create another generated wiki, another disposable index, or another chat memory trick.

It is trying to keep software intent, implementation evidence, graph memory, and agent context aligned.

The Missing Layer In AI Software Work

When we build software with AI agents, truth starts to spread across too many places.

The plan is in chat.

The intent is in documents.

The evidence is in code.

The relationships are in a graph.

The current answer is in a context window.

Each piece is useful, but none of them alone is the contract.

A chat can explain what we wanted yesterday, but it fades. A codebase can show what exists today, but code is evidence, not approved intent. A graph can reveal relationships, but graph memory should not pretend to be human-reviewed truth. A wiki can organize knowledge, but it does not automatically prove that implementation still matches the PRD.

That gap is where workspace-memory lives.

It is a contract layer for AI software work.

Why Not Just A Wiki?

Wikis are valuable. I like the wiki idea because humans need readable knowledge, not only machine data.

A wiki can summarize a project. It can connect notes. It can give humans and agents a shared place to read.

But a wiki alone does not solve the whole problem.

A software project needs more than organized pages. It needs rules, PRDs, ADRs, design constraints, project cards, validation, history, provenance, and checks against code evidence.

If a requirement changes, I do not want the old requirement silently erased.

If an agent notices that code no longer matches the PRD, I do not want the agent to rewrite the PRD by itself.

If two documents disagree, I want a conflict report that a human can resolve.

That is why workspace-memory keeps human-readable files, but does not stop there.

Why Not Just A Graph?

Graphs are powerful. They are excellent for relationships, dependencies, temporal memory, planning, and exploration.

But in workspace-memory, the graph has a specific role.

Human contract files are reviewed truth.

Neo4j is the primary memory and reasoning layer.

PostgreSQL is the ledger and operational store.

That means Neo4j is not a disposable view. It stores native graph knowledge, relationship assertions, code evidence, graph-first search state, graph-first context evidence, impact paths, and temporal lifecycle history. PostgreSQL does not own facts, requirements, decisions, search retrieval, relationship assertions, or graph memory backup. It records the operational ledger around the graph: source events, document versions, audit, LLM extraction runs, graph write receipts, reconciliation runs, validation report metadata, and context packet metadata.

Both stores are written from the same source ingestion event. Normal graph memory is not derived from PostgreSQL rows.

If Neo4j needs repair, the repair path is explicit graph reconciliation. It replays source events and writes graph receipts after successful graph writes. The graph is not rebuilt from PostgreSQL memory rows, because PostgreSQL is not the knowledge model.

The project truth still does not depend on a generated graph becoming human authority. Human files remain the contract. Neo4j is the machine reasoning layer that agents use. PostgreSQL is the durable ledger of what was ingested, extracted, written, audited, and reported.

Why Not Just An Agent Skill?

Agent skills are useful because they teach agents how to behave.

They can tell an agent: load this file first, respect this rule, use this command, never push to git, preserve old requirements before writing new ones.

But a skill is not durable memory.

A skill guides behavior. It does not become the system of record.

workspace-memory works well with skills because the skill can activate the workflow, but the memory system gives the agent something reliable to act from.

The skill tells the agent how to act.

workspace-memory gives the agent cited graph context, validated contract structure, and code evidence to reason from.

Agent-First, Not Agent-Owned

This is one of the most important design choices in the project.

workspace-memory is agent-first because it is designed for AI agents to use every day. Agents can request focused context, search graph memory, inspect conflicts, read project rules, validate code evidence, and understand how a project is supposed to work.

But it is not agent-owned.

Humans own the contract files:

• RULES.md
• WORKSPACE_GUIDE.md
• project cards
• PRD.md
• AGENTS.md
• DESIGN_SYSTEM.md
• ADRs and decisions

Agents do not silently replace those files.

If something changes, the old text should be preserved as unvalidated history with a timestamp. The new requirement can be added, reviewed, and validated. That keeps the project honest.

Code evidence also has a clear role. Code can show what has been implemented, but it does not automatically override human intent. If code and contract disagree, that should become a finding, not an invisible rewrite.

The interfaces follow the same boundary. The CLI has explicit local operator workflows for initialization, ingestion, graph reconciliation, code validation, and reports. MCP and HTTP API surfaces are read-only/source-safe: they can expose search, context, graph checks, graph impact, graph neighbors, conflicts, and existing validation evidence, but they do not expose direct database mutation, raw Cypher, migrations, source-file edits, graph repair, or event replay.

What workspace-memory Does

workspace-memory turns human-readable project intent into operational graph memory and ledgered evidence.

It validates human files before ingestion.

It uses deterministic source parsing to prepare paths, frontmatter, Markdown sections, spans, hashes, and source-event provenance.

LLM-assisted extraction is required for ingestion knowledge creation.

It validates LLM output before writing memory.

It writes native Neo4j graph memory synchronously.

It writes PostgreSQL ledger records and graph write receipts.

It preserves provenance back to source files.

It detects conflicts between human documents.

It validates implementation evidence against project contracts.

It writes observed code evidence into Neo4j for CLI wm validate-code runs.

It generates graph-first search results and graph-first context packets for agents.

It repairs graph memory through source-event replay, not PostgreSQL memory rows.

It supports many workspaces on one PostgreSQL instance and one Neo4j instance by scoping everything through a stable workspace_key stored in workspace-memory/.workspace-memory.json.

It exposes explicit CLI write workflows plus read-only MCP/API interfaces.

The LLM is important, but it is not trusted blindly. LLM output must be structured, schema-validated, cited, and stored with trust status such as observed or needs-confirmation until humans review it.

The deterministic part is source parsing, not knowledge extraction. Parsing can identify files, sections, spans, hashes, and provenance. It does not create replacement facts, requirements, decisions, graph nodes, or graph relationships when an LLM is unavailable.

The Temporal Layer

The graph also has to remember change.

A requirement can evolve. A decision can be superseded. A relationship between two concepts can change meaning. Code evidence can become stale when files or symbols change.

That temporal behavior belongs in Neo4j.

workspace-memory stores lifecycle-aware graph assertions with fields such as semantic_key, assertion_hash, lifecycle_status, validity windows, and superseded_by_key. When a current assertion changes, Neo4j preserves the old assertion, marks it as superseded, writes the new current assertion, and connects the new assertion to the old one with SUPERSEDES.

Relationship meaning gets the same treatment through RelationshipAssertion nodes. Traversal relationships still exist for graph walking, but the claim itself can have lifecycle history.

This lets agents ask for current knowledge by default while the system still keeps historical knowledge available for audit, reconciliation, and review.

The Self-Describing Workspace

One small detail captures the spirit of the project.

WORKSPACE_GUIDE.md is installed into the workspace memory folder and ingested as usage knowledge.

That means users can ask the workspace how the workspace works.

Where should PRDs live?

What does wm validate-code check?

What belongs in PostgreSQL versus Neo4j?

How should agents treat human contract files?

The answer can come from the same memory system the project uses for everything else.

That makes the tool teachable inside its own structure.

wm init is part of that story, but it has a narrow job. It creates or verifies workspace files and the stable identity file. It does not create PostgreSQL or Neo4j. Runtime services come from Docker Compose, or from managed/cloud PostgreSQL and Neo4j configured through environment variables. The operational setup belongs in the README and workspace guide; the important product point is that workspace identity and runtime services are explicit, not hidden inside chat or agent behavior.

The Real Problem I Wanted To Solve

I did not create workspace-memory because existing tools are bad.

I created it because they solve different parts of the problem.

LLM-Wiki is useful for shared knowledge.

Graphiti is useful for temporal graph memory.

Graphify is useful for turning files into graph and wiki-style outputs.

But I needed a project where human intent, Neo4j graph memory, PostgreSQL ledger records, source-event reconciliation, agent context, conflict detection, and code validation are part of one system.

I wanted a place where project truth does not disappear into chat.

I wanted code evidence to be useful without becoming the contract.

I wanted agents to have strong context without owning the source of truth.

I wanted old requirements preserved instead of overwritten.

I wanted the graph to be powerful, current, and repairable from source events.

I wanted a workspace that humans can edit and agents can use.

That is workspace-memory.

Keep Intent Human. Make Memory Operational

AI software work needs memory, but memory alone is not enough.

It needs a contract.

It needs a way to say: this is what humans agreed to, this is what the code shows, this is what changed, this is what conflicts, and this is what the agent should know before acting.

That is the reason for workspace-memory.

Chat fades.

Code drifts.

Agents guess.

So the project needs a place where intent survives.

That place should be readable by humans, usable by agents, graph-native for reasoning, and durable enough for production.

That is what I am building.

Comparison Table

Dimension	workspace-memory	LLM-Wiki / workspace-wiki	Graphiti	Graphify
Primary purpose	Production memory and contract system for AI-assisted software workspaces.	Markdown/Obsidian-style shared wiki maintained by an LLM agent.	Temporal context graph engine for AI agents.	Agent skill that turns a folder of mixed files into a queryable graph/wiki output.
Best use case	Multi-project software workspace where PRDs, rules, design systems, decisions, code evidence, graph memory, and agent context must stay aligned.	Shared workspace knowledge, cross-project summaries, durable linked wiki pages, and human-readable synthesis.	Building and querying evolving temporal graphs from structured and unstructured data.	Exploring a folder of code, docs, images, papers, and other files as a generated graph.
Source of truth	Human contract files are reviewed truth. Neo4j stores graph memory and reasoning state. PostgreSQL stores ledger, audit, document versions, source events, and graph receipts.	Raw source files and maintained wiki pages.	Episodes/raw ingested data behind derived temporal graph facts.	Input folder plus generated graphify-out/ artifacts.
Human contract files	First-class: RULES.md, WORKSPACE_GUIDE.md, project cards, PRDs, AGENTS.md, DESIGN_SYSTEM.md, and ADRs.	Wiki schema and pages are human-readable, but not a full software contract hierarchy.	Supports provenance, but does not define software-project contract files as the workflow center.	Produces graph/wiki outputs, but does not define PRD/rules/design-system contract governance.
Agent data relationship	Source ingestion writes Neo4j graph memory and PostgreSQL ledger records from the same source ingestion event. Search and context are graph-first. Agent data does not create new human-readable intent files.	The LLM maintains human-readable wiki pages as the durable knowledge layer.	The graph is the main agent-facing memory structure.	Generated graph/wiki files are the main agent-facing output.
Self-describing usage knowledge	WORKSPACE_GUIDE.md is initialized and ingested so users can ask agents how workspace-memory works.	A wiki can document itself, but it is not a built-in product usage memory layer for a software contract system.	Documentation exists outside the graph unless the adopter ingests it.	Usage is documented through skill/CLI docs and generated outputs, not a contract-system guide ingested as product knowledge.
Runtime/database layer	Neo4j is the primary memory and reasoning layer; PostgreSQL is the ledger and operational store. Both can serve many workspaces through strict workspace_key scoping.	Markdown vault/files; no production database source of record.	Graph backend such as Neo4j, FalkorDB, Kuzu, or Neptune, plus LLM/embedding services.	Local generated graph files; no Neo4j required, with optional Neo4j export.
Graph behavior	Native Neo4j graph writes happen during ingestion and code validation. Reconciliation repairs graph memory by replaying source events, not by deriving graph knowledge from PostgreSQL memory rows.	Wiki links and Obsidian-style graph navigation.	Core product is temporal context graph construction and querying.	Builds a local graph from files and exports visual/queryable artifacts.
Temporal model	Neo4j-owned lifecycle assertions with trust status, lifecycle status, validity windows, provenance, RelationshipAssertion nodes, and SUPERSEDES relationships.	Can preserve history through pages/logs, but no typed temporal assertion model.	Strong temporal facts with validity windows and historical queries.	Tracks extracted/inferred/ambiguous edges, but not a software-contract temporal memory model.
Code-vs-contract validation	CLI wm validate-code scans code, writes observed code evidence into Neo4j, and checks requirement-to-code evidence paths against PRDs, rules, ADRs, design system, and project cards.	Can support wiki-based analysis, but does not provide built-in code-vs-PRD validation.	Not focused on validating code against human software contracts.	Extracts code structure and relationships, but does not enforce PRDs or human contract files against implementation evidence.
Conflict detection	wm find-conflicts reports contradictions across human documents in a standard human-resolution format.	Wiki linting can find stale or inconsistent wiki pages.	Handles changing facts temporally, but not project-document conflict resolution as a human workflow.	Reports what it found or inferred, but not a human contract conflict workflow.
Agent/platform integration	CLI write workflows, portable AGENTS.md snippet, platform-independent skill reference, read-only MCP/API, and local HTTP.	Agent-maintained wiki workflow, prompts, and Codex/Claude-style usage.	Python framework, MCP server, and REST service for graph memory.	Claude Code skill with broader agent platform notes and local CLI outputs.
LLM dependency	Ingestion requires validated LLM-assisted extraction. Deterministic parsing supplies source structure, spans, hashes, and citations only.	LLM agent is central to maintaining the wiki.	LLM and embedding providers are central to graph construction/retrieval workflows.	Claude/LLM extraction is central for docs/images and richer graph creation; code AST extraction can be more deterministic.
Production readiness	Docker runtime, migrations, typed models, tests, config checks, health checks, CI, PostgreSQL, Neo4j, MCP/API.	Useful as a workspace knowledge vault, but not a typed production runtime.	Strong graph engine/framework; surrounding product workflow must be built by the adopter.	Useful generated graph/wiki tool; not a durable governance/runtime system for software contracts.
What it does not try to solve	It does not replace all research/wiki workflows, all graph engines, or all agent skills.	It does not operate as a database-backed memory runtime with code-contract validation.	It does not manage PRDs, AGENTS.md, design systems, project adoption, and workspace contract rules.	It does not become the authoritative source of project truth or manage human contract lifecycle.