Chat fades, code drifts, and agents guess. I needed one project that solves all three together.

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.

At first, it sounds like a strange thing to build. We already have tools for project knowledge. We already have wiki-style systems like LLM-Wiki. We already have temporal graph memory systems like Graphiti. We already have agent skills and graph-building workflows like Graphify.

So why another project?

Because AI-assisted software work has a different problem hiding underneath the surface.

The problem is not only remembering things.

The problem is knowing what the project actually agreed to.

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 graph is in a database.

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 a graph projection should not become the human source of 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, and exploration.

But in workspace-memory, the graph is not the source of truth.

Neo4j is a projection.

PostgreSQL is the durable record.

Human files are the contract surface.

That distinction matters. If the graph drifts, it can be rebuilt. If search chunks are stale, they can be rebuilt. If context packets are incomplete, they can be regenerated.

The project truth should not depend on one generated view.

It should come from human intent, validated records, provenance, and audit history.

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 stores the trusted project context.

The skill tells the agent how to act.

workspace-memory gives the agent something reliable to act 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 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.

What workspace-memory Does

workspace-memory turns human-readable project intent into operational memory.

It validates human files before ingestion.

It stores durable records in PostgreSQL.

It projects relationships into Neo4j.

It keeps provenance back to source files.

It detects conflicts between documents.

It validates implementation evidence against project contracts.

It generates focused context for agents.

It exposes read-only CLI, MCP, and API interfaces.

It can use LLM assistance, but the deterministic core must still work without an LLM.

That last point is important. The LLM can help, but it should not become the trusted core by itself. LLM output should be structured, validated, cited, and treated carefully until humans review it.

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.

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, durable memory, graph projection, 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, but rebuildable.

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, 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, 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 plus PostgreSQL durable records with provenance and audit.	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	Agent data is derived from human files and observed code, then stored in PostgreSQL, Neo4j projection, search chunks, context packets, reports, provenance, and audit records. It 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	PostgreSQL is durable source of record; Neo4j, search, and context are rebuildable projections.	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	Neo4j projection rebuilt from PostgreSQL; graph is not trusted as source of truth.	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	Explicit application-owned temporal assertions with status, validity windows, provenance, and supersession.	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	wm validate-code checks implementation evidence 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, 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	Deterministic core works with LLM disabled; LLM assistance is optional and schema-validated.	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.