DEV Community: Zachary Sturman

Automating Linear From Notion

Zachary Sturman — Mon, 18 May 2026 22:44:54 +0000

Planning often starts in Notion because it is flexible and easy to shape around a team’s workflow. Execution often moves into Linear because it is structured, fast, and better at handling active delivery. That split works for a while, until the same projects, milestones, and tasks start living in both places and slowly drift out of sync.

I built a Python service to close that gap. At first, it seemed like a straightforward integration problem: fetch records from Notion, fetch records from Linear, compare them, and push updates where needed.

It turned out to be more involved than that.

Once I started dealing with conflicting edits, relationship preservation, duplicate prevention, retry logic, and sync history, the project stopped being a script and became a real synchronization engine. The interesting part was not the API wiring. It was the architecture needed to make the sync reliable enough to trust.

What the Service Does

At a high level, the service keeps three kinds of records synchronized between Notion and Linear:

Projects
Milestones
Tasks

The sync is bidirectional, so changes can originate in either system.

On each run, the service:

Authenticates with both APIs
Fetches records from Notion and Linear
Normalizes them into shared internal models
Compares those models to detect meaningful differences
Decides whether to create, update, delete, or flag a conflict
Writes the result back to the opposite system
Repairs relationships and saves sync state for the next run

This is not a one-time import/export tool. It is designed to behave like an ongoing system.

Why the Problem Is Harder Than It Looks

The surface mapping seems simple.

A Notion project page roughly maps to a Linear project.

A Notion milestone page roughly maps to a Linear milestone.

A Notion task page roughly maps to a Linear issue.

But once those entities need to move back and forth reliably, the mismatch appears quickly.

Notion and Linear do not share the same schema. Their IDs are different. Their status systems are different. Parent-child relationships need to survive sync. Both sides can change the same record before the next run. APIs can fail or rate limit. And if the service loses track of what it already created, duplicates show up fast.

Even something as small as task status is not a simple field copy.

In Notion, a task might have a human-readable status like To Do or In Progress. In Linear, an issue belongs to a workflow state with both a label and a state type such as backlog, unstarted, started, or completed.

A reliable sync cannot compare labels alone. It has to compare meaning.

That shifts the real problem from “moving data between APIs” to “building a system that can preserve identity, structure, and semantics across two different tools.”

The Design Decision That Made the Project Work

The design decision that made the whole service workable was introducing a shared internal model layer.

Instead of comparing raw Notion responses against raw Linear GraphQL nodes, the service translates both into unified Python models first. Projects become UnifiedProject, milestones become UnifiedMilestone, and tasks become UnifiedTask.

That gives the sync engine a stable internal language.

Once everything is normalized into a shared representation, the rest of the architecture becomes much cleaner:

The reconciler compares like with like
Conflict logic operates on consistent fields
Platform-specific translation stays at the edges
The codebase no longer scatters Notion-vs-Linear conditionals everywhere

The flow looks like this:

Notion API data + Linear API data
                ↓
        Unified internal models
                ↓
         Reconcile differences
                ↓
      Write changes to target side
                ↓
      Resolve relationships + save state

The unified model is not just a convenience layer. It is what makes reconciliation possible.

System Structure

Once the internal model layer was in place, the rest of the service settled into a fairly clean architecture.

Configuration

Handles environment variables, API credentials, database IDs, field mappings, and conflict strategy settings.

API clients

Wrap Notion and Linear directly. They handle authentication, requests, pagination, rate limiting, and platform-specific response structure.

Unified models

Represent the internal source of truth used by the sync engine.

Mappers

Convert records into and out of the unified models. They also translate semantics, such as mapping Notion priority labels to Linear priority values or converting Linear workflow states into a Notion-friendly status representation.

Reconciler

Compares normalized records and decides whether each one should be created, updated, deleted, or treated as a conflict.

Relation resolver

Repairs relationships after base records already exist in both systems.

State store

Keeps durable sync memory: linked IDs, timestamps, content hashes, and prior sync metadata.

Utilities

Cover retries, rate limiting, logging, and CLI support.

A simplified view of the architecture looks like this:

CLI
→ Config
→ API Clients
→ Unified Models
→ Mappers
→ Reconciler
→ Relation Resolver
→ State Store
→ Notion / Linear APIs

Following One Task Through the Pipeline

The easiest way to explain the sync flow is to follow a single task through it.

Imagine someone creates a task in Notion called Write API docs. They set:

status = In Progress
priority = High
sync enabled = true
linked project and milestone

The service fetches that page from Notion and parses it into a unified task model. At that point, it is no longer reasoning about raw Notion properties. It is working with an internal task record that contains fields like title, status, priority, relation IDs, and last modified time.

From there, the mapper translates platform-specific meaning.

For example:

Notion High priority becomes the Linear priority value expected by the target API
Notion In Progress becomes a normalized internal state
That state is then matched to the appropriate Linear workflow meaning rather than copied literally

The reconciler compares that unified task against the matching Linear issue, along with persisted sync state from earlier runs.

If no matching Linear issue exists, the engine creates one.

If one exists but differs, it updates it.

If both sides changed incompatibly since the last successful sync, it becomes a conflict.

Once the write succeeds, the service stores the Notion ID ↔ Linear ID mapping locally so future runs know both records represent the same task.

If some relationships could not be applied immediately, the relation resolver reconnects them later once all required cross-system IDs exist.

That miniature pipeline captures the whole system:

normalize → compare → decide → write → reconnect → remember

What Counts as a Real Change

One of the subtler design problems was deciding what should count as a meaningful change.

A sync engine cannot just ask whether two payloads look different. It has to ask whether they are semantically different in a way that should trigger an update.

To do that, the service combines several signals:

linked identity
modification timestamps
normalized content
persisted sync state

For each synced entity, the local store keeps:

Notion ID
Linear ID
last modified times from both sides
normalized content hash
last sync metadata

Each signal matters, but none is enough on its own.

IDs tell the system what matches, but not what changed
Timestamps can be noisy
Raw payloads can differ in representation without differing in meaning
State is what makes those signals useful together

This is where the service stopped behaving like a script and started behaving like an engine.

The Two Things That Made It Reliable

Two parts of the design mattered more than almost anything else:

relationship handling
persistent sync state

1. Relationship handling

Relationships are easy to underestimate.

A task can belong to a milestone.

A milestone can belong to a project.

A task can also have a parent task.

If every record is synced independently in one pass, many of those references fail simply because the destination record does not exist yet.

The solution was a two-pass strategy.

First pass: create or update base records

Second pass: repair project, milestone, task, and subtask relationships once cross-system IDs are known

That second pass is handled by a dedicated relation resolver that uses lookup maps in both directions.

2. Persistent sync state

Without local state, the service has no durable memory.

It can fetch data and compare timestamps, but it cannot truly know:

what it created before
what changed semantically
whether a record is genuinely new
whether two records are already linked

So the service keeps a local SQLite store with:

linked IDs
timestamps
content hashes
prior sync metadata

That gives the engine continuity across runs. It can avoid duplicates, detect changes more accurately, and treat sync as an ongoing process instead of starting from zero each time.

One Failure Mode That Changed the Design

One of the most useful failure cases was also one of the simplest: duplicate creation after partial success.

Imagine the service successfully creates a record in the target system, but fails before persisting the new linkage locally.

On the next run, that same source record can still look unsynced. The engine may then create a second copy.

That is the kind of bug that does not show up in a clean demo but appears quickly in a real system.

It reinforced an important design lesson: local sync state is not just metadata for convenience. It is part of the identity model of the system.

The same pattern showed up with relationships. Creating a task before its milestone mapping existed was not really an API bug. It was a sequencing problem.

That realization pushed the design toward explicit relation repair instead of trying to force everything into a single perfect pass.

Making It Safe to Run

Once the happy path worked, the next question was whether the system behaved well under ordinary failure conditions.

That meant adding:

retry logic with exponential backoff
explicit rate limit handling
dry runs through the CLI
structured logging around every sync action
configurable conflict resolution

The retry layer wraps API calls with backoff and jitter, while rate limiters help avoid throttling before it happens.

The CLI also matters more than it might seem. The sync can run:

bidirectionally
Notion → Linear only
Linear → Notion only

It can also be scoped to:

projects only
milestones only
tasks only

And dry-run mode lets you inspect intended actions before allowing writes.

Conflict handling had to be configurable too. In a bidirectional sync, there is no universal answer to which side should win when both records changed.

Depending on the workflow, the right strategy might be:

last-write-wins
Notion-primary
Linear-primary

Those operational features are less visible than the core data flow, but they are what make the tool usable outside of controlled demos.

What I Learned

The biggest lesson from the project is that synchronization problems stop being API problems almost immediately.

At first, I assumed most of the work would be authentication, field mapping, and request handling. Those pieces mattered, but they were not the center of the challenge.

The hard part was:

defining a stable internal model
preserving relationships across systems
deciding what changed in a meaningful way
keeping enough memory of earlier runs to avoid guessing

In other words, the core problem was not moving data. It was establishing internal truth.

Once that became clear, the APIs stopped being the main event. They became edges. The architecture in the middle became the actual product.

Tradeoffs

That architecture comes with tradeoffs.

A unified internal model makes reconciliation much easier, but it also means the mapping layer has to evolve as either API changes.

Persistent local state makes the system safer and more reliable, but it adds operational surface area. Once identity, timestamps, and hashes are stored locally, that state becomes part of the product.

And bidirectional sync is far more useful than a one-way export, but it guarantees that conflict resolution is not an edge case. It is part of normal operation.

Those tradeoffs were worth it. But reliability here comes from accepting complexity and placing it deliberately at the center of the system rather than pretending it is not there.

If you want the broader workflow around that sync, I wrote more about how I use Notion to track my projects at https://zachary-sturman.com/articles/how-i-use-notion-to-track-my-projects and how I sync my portfolio using Notion at https://zachary-sturman.com/articles/how-i-sync-my-portfolio-using-notion.

If this kind of system design and reliability-focused architecture is interesting to you, you can explore more of my work at zachary-sturman.com, or dive into the full implementation on GitHub: https://github.com/ZSturman/Linear-Notion-Sync.

How I Sync My Portfolio Using Notion

Zachary Sturman — Tue, 12 May 2026 11:59:51 +0000

For a while now, I have wanted my portfolio to work less like a hand-edited website and more like a publishing pipeline.

I do not want to update the same project information in five places. I do not want portfolio pages to be their own isolated source of truth. I want project data to live upstream in a structured system, get transformed once, and then flow into the site in a predictable way.

That is the setup I use now.

At a high level, the process is simple: I manage project information in Notion, use n8n to assemble that data into a JSON export, run local Python build scripts to turn that export into a static content layer, optimize the media, sync in articles from a separate source, then let Next.js export the site and Firebase serve it.

A lot of the structure in this pipeline is also a holdover from an older project of mine called Folio. The current site no longer runs through Folio itself, but parts of the naming and architecture still come from that earlier phase. That is why one of the main scripts is still called lib/folio-prebuild.py even though the portfolio is now built from Notion, n8n, JSON exports, and static publishing.

I am writing more about that backstory separately at zachary-sturman.com/articles/the-art-of-turning-a-90-minute-task-into-a-2-month, but the short version is that I spent a long time trying to build a structured project record that could feed multiple outputs. I no longer use that system directly, but the output-oriented thinking survived, and this pipeline is what that evolved into.

Notion is where the content starts

The source of truth for this setup starts in Notion.

That is where I keep the project information that eventually becomes the portfolio: titles, summaries, statuses, assets, resources, collections, work logs, and other structured relationships that help define a project beyond just a name and thumbnail.

I have a separate article about how I use Notion for this in more detail here:

https://zachary-sturman.com/articles/how-i-use-notion-to-track-my-projects

So I do not want to repeat all of that here. The relevant part for this article is just the handoff: Notion is where the information is authored and organized, but it is not where the portfolio gets assembled.

That distinction matters.

The website does not query Notion directly. The frontend does not know how my databases are structured. The build process does not depend on live requests into my workspace. Instead, I use Notion as the editorial layer, then convert that into a local export the site can build from.

That keeps the website side simpler and makes the publishing process more deterministic.

The shape of this pipeline still comes from Folio

One thing that is probably worth explaining early is why parts of this setup still look the way they do.

The current portfolio pipeline grew out of an older system I built called Folio. That older work went through a lot of versions, but one of the most consistent ideas across them was this: a project should exist as a structured record that can feed multiple outputs.

That could mean a portfolio page, a local document, a media view, an archive, or something else. The exact interface changed a lot over time, but the idea of one structured project record powering more than one destination kept surviving.

That is the relevant part here.

The current pipeline does not use Folio as its runtime system, but it still carries some of that architecture forward. The naming is one example. The reason the build script is still called folio-prebuild.py is not because the current site depends on Folio. It is because the pipeline was reworked from that earlier structure instead of being renamed from scratch after every architectural shift.

So if some of the codebase has older names attached to newer responsibilities, that is why.

If you do not care about the longer backstory, the short version is this: I used to try solving this problem with a much more custom system. Now I use Notion for the editing layer, but I kept the idea that structured project data should be transformed into a reusable content layer before the frontend touches it.

n8n turns the Notion data into a build input

The next step is n8n.

This is the bridge between the editorial structure in Notion and the actual build input used by the portfolio.

My n8n workflow pulls data from several parts of my Notion setup, merges the records together, reshapes them into the structure I want, and writes out a JSON file that the local build step can consume.

In the screenshot above, the workflow is doing a few distinct jobs:

it starts from a trigger
it queries the relevant Notion databases
it merges those streams together
it assembles the nested JSON structure
it writes the export to disk
it logs success or failure back into Notion

That export becomes the portfolio handoff.

This is a useful separation point in the system because it means the site build does not need to know anything about Notion’s API, my database layout, or the internal structure of my workspace. n8n handles the extraction and reshaping, and the repo only needs to deal with the exported file.

That file is new_projects.json.

Once that exists, the website side can treat it as the source input and move on.

Building the routes

Once the export exists, the portfolio build becomes a local file transformation problem.

That is the point where I stop thinking in terms of Notion pages and start thinking in terms of static site inputs.

The main entry point for that part of the process is lib/folio-prebuild.py.

Even the top docstring in that file says exactly what it is doing:

Build public/projects from n8n-exported new_projects.json.

That is the real handoff.

The script takes the JSON export, passes it into the normalization pipeline, builds the public project output, writes supporting manifests, and publishes the result into the public directory where the site can use it.

The command that matters most here is basically this:


npm run generate-projects

And under the hood, that maps to a Python build step that points at the exported JSON file and runs lib/folio-prebuild.py.

I like this setup because it makes the expensive content-building work explicit. It is not hidden inside deployment. It is not mixed into the frontend runtime. It is a clear, local step.

That also makes it easier to reason about when something goes wrong. If there is a bad field, a missing asset, a malformed relationship, or a path issue, I can catch it at the build layer before it becomes a broken route on the site.

The project build step turns raw records into website-shaped data

This is the core of the whole process.

The job of the project build step is not just to copy a JSON file from one place to another. It is to take data that is still shaped like an export and normalize it into something the site can actually trust.

That includes a few important steps.

First, it validates the input and builds a normalized project representation. The entry script delegates most of that work into projects_pipeline.py, but folio-prebuild.py makes the role clear: it creates a temporary build directory, calls the pipeline, writes the final output, and atomically replaces the public projects folder.

Second, it creates the project manifest the frontend uses. The script writes a projects.json file into the generated output. That becomes the main data layer for project content on the frontend side.

Third, it writes image-hostnames.json, which gives the frontend a controlled list of external image hosts that are allowed. That is a small detail, but it is part of what makes the build output feel like a complete content layer instead of just a loose export dump.

Fourth, it handles a lot of defensive filesystem behavior. This is one of the places where the older pipeline DNA is still visible, and I think it is useful. The build step uses a lockfile so I do not accidentally run overlapping builds. It writes into a temporary directory first. It atomically replaces the public output when the build succeeds. It keeps a backup path if the old directory cannot be removed cleanly. It also includes repair logic for the cloud-sync issue where a folder can get renamed to something like projects 2 instead of staying canonical.

That part is not glamorous, but it is the kind of detail that makes a local publishing pipeline more trustworthy.

This is also the stage where one abstract project record becomes something much closer to a real page on the site. Titles, slugs, paths, media locations, related resources, collections, work logs, and article references all start getting shaped into the form the frontend expects.

This is where the portfolio stops being “my project data” and starts being “the site’s content layer.”

Every project gets a canonical route and a stable public folder

One of the important outcomes of the build step is that each project gets a canonical route and a stable public folder.

That matters because a portfolio stops feeling solid pretty quickly if the URL structure is inconsistent or if media paths are fragile.

The pipeline solves that by normalizing titles into stable slugs, generating clean hrefs, and copying referenced media into project-specific folders under public/projects/....

In practice that means the project data can be authored upstream however I need it to be, but by the time it reaches the site it has a canonical route shape. The frontend is not guessing how to build project URLs from raw records. It gets a clean manifest that already encodes that decision.

Conceptually it looks like this:


project record

→ normalized slug

→ canonical href

→ generated project folder in public/projects/

→ route rendered by the site

That is one of the reasons I like doing the normalization before the frontend touches anything. It keeps the React and Next.js side of the system much thinner.

The frontend does not need to negotiate the messy version of the data. It only has to render the cleaned version.

Articles are a second content source

The portfolio is not built from project JSON alone.

Articles come in through a separate sync process.

That matters because the site is not just a projects grid. It also includes writing, and I wanted articles to live in a structure that could be generated and normalized the same way instead of being hand-wired page by page.

The article sync stage pulls from a separate repository, discovers the available markdown content, rewrites relative links into portfolio-local paths, copies referenced assets, and builds out a normalized article structure under public/articles.

It also resolves project references in article frontmatter into canonical project IDs. That is a small but important detail, because it keeps article-to-project links stable even if the original reference came in as a title, slug, or some other upstream identifier.

That gives me a content model where projects and articles are separate sources, but both end up flowing into the same static publishing layer.

So even though the project data and article content start in different places, they get normalized into a shared output shape before the site is exported.

Media optimization is part of publishing, not just cleanup

After the raw project media is copied into the public project folders, there is another step that matters just as much: optimization.

That happens in lib/media-optimizer.py.

The goal here is to generate the versions of the media that the site actually wants to serve, not just preserve the originals.

For images, that means creating optimized WebP versions, smaller thumbnail variants, and blur placeholders for loading states. For videos, it means generating smaller web-ready MP4 files along with thumbnails and placeholders. For some 3D assets, it can also convert models into formats that are easier to serve on the web.

The point is not just to compress files for the sake of compression. It is to make the output layer actually reflect the way the frontend wants to consume media.

That is why I think of this as part of publishing rather than maintenance.

The script itself is very direct about this. It defines the optimized variants, checks for tools like ffmpeg, handles images, videos, SVGs, and some 3D models, and writes the generated assets alongside the originals with consistent suffixes like:


image.jpg

image-optimized.webp

image-thumb.webp

image-placeholder.jpg

video.mp4

video-optimized.mp4

video-thumb.jpg

video-placeholder.jpg

That is also why the Git strategy makes sense the way it does. The optimized derivatives are part of the site output. They are not disposable side products.

The frontend treats the generated output like a static content API

Once the project build, article sync, and media optimization steps are finished, Next.js can treat the generated files as a content layer.

That is one of the cleanest parts of the architecture.

The frontend does not need to know where the data came from upstream. It does not need to understand Notion or n8n. It does not need to rebuild relationships on the fly. It just reads the manifests and files that were already generated.

The homepage reads from the generated project manifest. Project detail pages and article routes are derived from the generated content. Media helpers can request the optimized variants automatically. And because the site is configured for static export, the build writes a fully static output that can be hosted directly.

That means the architecture ends up looking something like this:


Notion + article source

→ export + sync

→ normalized manifests + copied media

→ optimized delivery assets

→ Next.js static export

→ deployed portfolio

I like this because it gives me a dynamic editing process upstream and a very static, predictable delivery layer downstream.

Those are different jobs, and I do not think they need to be solved in the same place.

I keep the expensive assembly work local before push

One of the biggest design decisions in this setup is that content generation happens before push, not inside CI.

That means the local machine does the heavier work:

generate project data from the exported JSON
sync articles
optimize media
verify the output

Then CI stays relatively thin.

GitHub Actions does not regenerate project data, rebuild article content from scratch, or run the expensive media pipeline as the primary publishing step. It mainly installs dependencies, runs the site build, and deploys the already-generated state.

I like that separation for a few reasons.

First, it keeps deploys faster and more deterministic. The build server is not trying to replicate my whole content-generation environment.

Second, it means the checked-in generated artifacts are part of the known state of the repo. The build is using a precomputed content layer instead of hoping the upstream dependencies behave the same way in CI every time.

Third, it makes the workflow easier to reason about. The assembly process is local and inspectable. The deploy process is mostly just packaging and publishing.

That is a much calmer model than doing everything in one step on every push.

There are a lot of guardrails because local build pipelines are easy to trust until they break

A local publishing setup like this is only useful if it is hard to accidentally break.

That is where a lot of the more defensive details start to matter.

The build script uses a lockfile so I do not run overlapping builds into the same public directory. It writes into a temporary directory first and only replaces the output when the build has succeeded. It can back up the old generated folder before replacement. It includes cleanup logic for stale backups and stray sibling directories. And it even has post-build verification and repair logic for cloud-sync rename collisions.

The media layer has similar practical concerns. It checks for tool availability, handles different file types differently, and can batch-optimize entire directories while skipping already-generated derivatives.

None of that is particularly article-friendly in a visual sense, but it is the part of the system that keeps the whole thing from feeling brittle.

There is also a broader quality gate before deployment. Unit tests cover transformation logic, browser tests cover key user-facing flows, and the pre-push hook is strict about generated media being in a clean state.

That is important to me because generated content pipelines are one of those things that can feel stable right up until one missing asset, stale file, or half-finished build quietly makes it into production.

I would rather the system be annoying early than surprising late.

Why I still like this architecture

The main reason I like this setup is that it gives me a good boundary between authoring and publishing.

Notion is good for structured editing and maintaining the project record. n8n is good at assembling that into a clean handoff. Python is good at normalization, copying, repairing, and turning that handoff into a static content layer. Next.js is good at rendering the final result once the content is already in the right shape.

Each part has a clear job.

And even though a lot of this architecture still carries the shape of older experiments like Folio, I think that is fine. That history is the reason the system looks the way it does. I did not arrive at this setup by designing a perfectly clean pipeline from scratch. I arrived here by repeatedly trying to solve the same underlying problem, then keeping the parts that still felt useful once I stopped wanting to maintain a fully custom app.

So the current portfolio is less of a standalone site and more of a publishing endpoint.

The work of structuring the project data happens upstream. The work of normalizing and packaging it happens locally. The site just serves the result.

That feels like the right division for me right now.

If you are building something similar, that is probably the main takeaway I would offer: do not make your frontend solve editorial and publishing problems if you can solve them once upstream instead.

Closing

This pipeline is not just a way of updating my website. It is the current version of a longer idea I have been iterating on for years.

The older Folio work is the reason parts of the naming and structure still look the way they do. Notion is the reason the day-to-day editing side now feels lighter. n8n is the bridge that turns structured records into a usable export. The Python scripts are where the portfolio becomes website-shaped. And the static build is what lets the final site stay simple.

That combination works better for me than trying to make one custom tool do everything.

It lets me keep the structured project record idea that I still care about, without also turning the maintenance of the system itself into the main project.

Building a Location-First Learning Agent to Explore Context, Memory, and Consciousness

Zachary Sturman — Sat, 02 May 2026 22:56:38 +0000

Maybe recognition is less about detached labels than it is about where something is, what surrounds it, and how that context gets reinforced. That is what pushed me to build this repo. I wanted a smaller problem that still felt close to the thing I cared about. The question that kept pulling me back was whether location and context are a big part of knowing something at all, and whether they help make object recognition faster and more grounded.

That led me to build a small location-first learning agent. Right now it is a Python CLI project that learns from scalar observations and simple file-backed sensor inputs, stores what it learns in plain JSON and JSONL, and keeps the whole state inspectable. It is not a finished cognitive architecture, and it does not pretend to be one. What it gives me instead is a controlled place to test a very specific idea: maybe recognition does not start with detached labels, maybe it starts with where something is, what surrounds it, and how that context gets reinforced over time.

I also made a deliberate structural choice early on. I started out working with Thousand Brains Project Monty, but I split this work into a separate repo because I wanted a simpler environment where I could move directly on the parts I was most interested in. I did not want to spend my time threading a new experiment through a larger existing system before I understood the experiment itself.

Why I started with location

There are plenty of ways to make a toy agent look smarter than it is. I was more interested in making one that was inspectable. That meant I needed a narrow problem, a tight loop, and data structures I could read without translation.

So the first version of this project was almost stubbornly small. It learned grayscale observations mapped to location labels, persisted them across sessions, and logged each interaction. That sounds minimal, and it is, but it gave me a starting point for a question I still care about: if an agent repeatedly encounters a signal in a place-like context, what should it actually remember, and what should count as the identity of that memory?

The repo has moved through a few clear phases since then:

Phase 1 bootstrapped exact-match grayscale memory with persistence and append-only logging.
Phase 2 added noisy scalar matching and confidence thresholds.
Phase 3 merged repeated observations into location models instead of treating every value as a separate record.
Phase 4, the current phase, introduces first-class labels, aliases, rename history, sensor bindings, and provenance-aware evidence records.

That progression matters to me because it shows the shape of the project. I am not trying to jump straight from nothing to a full theory of mind. I am trying to build up a memory system that stays small enough to reason about while it gets more structured.

What the current project actually does

At the moment, this project is a stdlib-only Python CLI with no external packages required. I can run it, enter a grayscale value between 0.0 and 1.0, and either teach it a new location label or confirm a guessed one. It stores learned state in runtime/location_memory.json and appends interaction events to runtime/agent_events.jsonl.

That by itself would be a modest memory toy, but the current phase adds a few pieces that made the project feel more meaningful to me.

First, the system no longer treats the label as the identity. A location model now points to a label_id, and the label itself lives as a separate node with a canonical name, aliases, and rename history. That sounds like a small refactor, but it changed the shape of the project. Once I separated the thing being remembered from the latest name attached to it, a lot of awkward cases stopped feeling awkward. A label could change without pretending the location itself had changed. An alias could be useful without becoming a duplicate. A wrong guess could be corrected without discarding the old path through the system.

Second, scalar matching is not just nearest-prototype matching anymore. If the same location is confirmed across a wider range of observations, the system treats that inclusive span as learned territory. In practical terms, if I teach one location at 0.10 and 0.30, a later value like 0.28 can default to that same place unless conflicting evidence shows up. I like this because it feels closer to how a memory should broaden, not just average.

Third, the current phase adds a sensor preview through sense /path/to/file. This lets the agent learn or recognize a file-backed input and bind it to a location. The important limitation is that it does this through exact file fingerprinting. It hashes the file contents, stores the fingerprint, and re-recognizes that exact input later. That is useful as a stepping stone, but it is not the final perception model I want. I have been careful in the repo docs to describe it as a temporary preview, because I do not want a convenient shortcut to quietly become the architecture.

The design decision that mattered most: identity is not the same thing as a name

The strongest technical decision in the current codebase is also the one that feels most conceptually important to me: label identity should be separate from the human-readable name.

In earlier versions, the mapping between a learned signal and a label was much flatter. That worked for bootstrapping, but it also made the memory feel brittle. If the name changed, the memory structure had to behave as if the thing itself changed. If I wanted synonyms or better naming later, I was really just patching a string field.

Phase 4 changes that by introducing LabelNode and storing label ownership through label_id. The location model keeps its own identity. The label keeps its naming history. Aliases stay attached to the same node. Wrong-guess corrections can rename the canonical label while preserving the old name as an alias. That is a cleaner technical model, but it also gets closer to the question that motivated the project in the first place. A remembered thing should not vanish just because I describe it better later.

This also made the inspectability better. The inspect command can now surface canonical label, aliases, label id, prototype, spread, observation count, and rename count in one place. The runtime schema also carries sensor_bindings, graph_edges, concept_nodes, and evidence_records, even though some of that is still scaffolding for later phases. I like that the state can be read directly. I can see what the agent knows, why it knows it, and which parts are still placeholders for future work.

The second big decision: keep the sensor preview useful, but refuse to confuse it with perception

One of the easier traps in projects like this is letting a convenient shortcut turn into a story about capability. The current image sensing path is useful because it gives me a way to test the learning loop with actual files and a repo-local media pack. The repo now includes generated-local Phase 4 fixtures, a media catalog, and scenario manifests so that part of the project stays deterministic and testable.

That part is real, and I think it is valuable.

What is not real yet is content-based perception. The system is not identifying rooms from visual structure, learned features, or scene composition. It is binding exact file fingerprints. The docs are explicit that later phases should move toward an ObservationBundle contract, region attention, primitive percepts, cue composition, and eventually a broader memory-and-attention engine. I think that distinction matters, because otherwise it would be easy to oversell what is happening now.

For the article, I want to be clear about both sides of that. The current preview is not nothing. It gave me a practical way to test location binding with deterministic image fixtures. But it also is not the end state, and I do not want to talk about it as if it already solves perception.

Why I kept the implementation plain

This project is intentionally plain in a few ways. It is stdlib-only. The CLI is synchronous and line-oriented. Persistence is single-writer JSON and JSONL. None of that is glamorous, and I am fine with that.

The benefit is that the moving pieces stay readable. The memory store is a JSON document. The event log is append-only. The tests say what the current phase is expected to do. The decisions file says why I changed the model when I did. Even the limitations are documented pretty directly, including the fact that Phase 4 still has pending manual acceptance even though the automated suite passes.

That simplicity fits the purpose of the project. I am not trying to hide the structure behind a polished interface yet. I am trying to make the structure legible enough that I can tell when a design choice actually helps.

What is implemented, and what is still only a roadmap

This is where I think a lot of projects get muddy, so I want to keep it clean.

persistent scalar learning with confidence and span-aware matching
first-class labels with aliases and rename history
exact-file sensor binding for a temporary image-preview path
provenance-aware evidence records restricted to user or sensor sources
repo-local fixture images, scenario manifests, and validation checks

Documented for later, but not implemented yet:

ObservationBundle
ExperienceFrame
MemoryUnit
activation competition
replay
resurfacing
reconsolidation
richer body-relative and multimodal context

I have already written those future concepts into the roadmap because I want a stable direction for the project, but I do not want to collapse the distinction between "planned" and "running." Right now this is still a location-first learning system with a broader cognitive direction, not a finished memory engine.

What I learned from building it this way

The main thing I learned is that narrowing the scope did not make the project less interesting. It made the interesting parts easier to see.

Separating label identity from naming made the whole memory story cleaner. Treating repeated confirmations as reinforcement rather than duplication made the learned state feel more coherent. Keeping the sensor preview deliberately temporary forced me to write down what I actually mean by perception instead of hiding behind a convenient shortcut.

I also learned that inspectability changes how I think about progress. A project like this can sound more advanced than it is if I only describe the aspiration. The files, tests, schema versions, and event logs keep me honest. They give me something concrete to evaluate, and they make it easier to notice when a new feature is really just a patch over a muddled model.

Where I want to take it next

The project is still a work in progress, and I plan to keep iterating and testing it in my free time. The next steps in the repo point toward richer context, typed concept scaffolding, and eventually a more general memory-and-attention layer, but I am still treating the current implementation as the thing that has to earn the next layer.

That is probably the clearest way I can describe the project right now. I started it because I wanted a personal space to test ideas about consciousness. I narrowed it to location and context because that felt like something I could actually build and inspect. Now I am using that smaller system to figure out which ideas survive contact with code.

I will post more about it after I have a better sense of what it can and cannot do. If you have thoughts about location, context, or memory design, I would be interested to hear them. The project is still early enough that those conversations can still influence how I shape the next layers.

If you want the broader architectural direction this is growing into, I wrote more about that here: https://zachary-sturman.com/articles/consolidating-an-offline-first-episodic-memory-system.

If you want to follow along you can find the repo here:

Repo: https://github.com/ZSturman/Train-of-Thought-Agent
GitHub: github.com/zsturman
LinkedIn: linkedin.com/in/zacharysturman
Portfolio: zachary-sturman.com
Email: Zasturman@gmail.com

The Wolf Project - Reworking a Real-World Project

Zachary Sturman — Mon, 27 Apr 2026 21:06:25 +0000

A few weeks ago I watched a Dodo video about The Wolf Project that stayed with me more than I expected.

https://www.youtube.com/watch?v=NMf8mlxO4sk

After that, I tried to find more information about what I had just watched. When I googled ‘the wolf project’ there was obviously a lot of options so I went to their Instagram page:

https://www.instagram.com/_wolf_project/

I sent a message, Megan responded, and she made it clear that help on the site itself would actually be useful. That became the starting point.

Where the Project Started

The existing site did what it needed to do at a basic level. It explained the mission, shared stories, and gave people a way to engage.

The site had everything it needed for the moment, but it was missing the actual layers Megan was wanting like the ability to have specific animal stories showcased, specific dollar amount shown per case plus blogs and an application process for others to get on board.

What I’ve Been Working On

The current version is built with Next.js and uses Firebase for authentication and data, with Cloudinary handling image storage.

Cases, blog posts, and site-wide content are stored in Firestore, which means updates are persisted and reflected immediately on the site. This is building the first parts of the real system Megan is looking for.

That change shifts how the project can be used.

Structured data for cases, blog posts, and shared site content
Image uploads that don’t rely on local assets
Seeded demo data so the site is usable without setup

There’s still work to do, especially around polish and edge cases, but the foundation is in a much better place than it was.

Current State

The dev version of the site is live here:

https://the-wolf-project-14stqkkgr-zsturmans-projects.vercel.app

The original site is still available here:

https://yourdogcanstay.com

It’s still a work in progress. There are areas that need refinement, and some features that haven’t been fully implemented yet. But it’s at a point where it’s usable and where feedback is actually helpful.

If you’ve seen the story or care about the space this project is working in, there’s room to contribute, whether that’s through feedback, design suggestions, or development.

What Comes Next

There are a few areas I’m focused on next:

Tightening up editing and data validation
Improving how donation data is handled and displayed
Cleaning up remaining assumptions around static content
Making sure the system is stable enough for real usage

The goal is to make sure the site can actually support the work it’s tied to, without becoming something that needs constant technical maintenance.

How’s My Eating?

Zachary Sturman — Thu, 15 Aug 2024 06:17:16 +0000

“Breathe”
"The food’s not going anywhere."
"Are you in a race?"

I eat too fast. It’s something that’s been an issue in my life for as long as I can remember. I always finish my food way faster than the people around me.

Sitting in front of the TV, barely chewing my food, and missing the moment when my body tries to tell me I’m full—binge eating can be a challenging habit to break, mostly because it’s really, really hard for me to pull my concentration away from the act of eating to the act of self-control.

There are a lot of benefits of slowing down:

Mindful eating habits lead to healthier food choices
Avoiding overeating by listening to your body
Quality of life increases when you actually taste what you're eating

I’ve tried a lot of different ways to slow down my eating like matching my bite pace with someone who eats slower and counting my chews.

These strategies have their downsides, such as:

Distraction from social interactions
Not allowing yourself to enjoy the flavors
And it's just hard to maintain long enough to build habits

"There's an app for that"

“How’s My Eating?” is an app designed to provide real-time notifications about your eating habits. Specifically, the app would monitor your eating pace or chew count and alert you if you’re eating too fast. This could lead to:

Healthier eating habits
Better digestion
More enjoyment of food

How to Make It?

To achieve this, I decided to focus on kinetic data—movements and patterns captured by devices like AirPods. This method is less intrusive and more feasible for users who value privacy.

I’m excited to continue developing “How’s My Eating?” and share my progress with you. This is the first post I’ve made in this format, so I hope it came across well. I plan to develop a schedule to keep these updates coming, but for now, let’s aim for one post a week.