Memoflow

Persistent repo memory for AI coding workflows

Memoflow keeps the story of your work close to the code, so your team and your AI tools can pick up a feature with the same clarity you had when you last touched it.

Quick Start See Team Handoff
  • Encrypted local memory for each repository
  • Built for real debugging threads, task notes, and feature work
  • Queryable context for assistants, scripts, and local tooling

Overview

Documentation for the memory layer behind calmer AI coding

Memoflow is a Ruby gem that helps teams preserve local working context between sessions. Instead of leaving the next developer or your future self to guess what happened, Memoflow keeps notes, commit clues, and task history connected to the repo.

Capabilities

What Memoflow captures

Think of Memoflow as a memory layer that travels with the project. It quietly stores the context that usually gets lost between sessions, handoffs, and bug-fixing rounds.

  • Git commit metadata, changed files, timestamps, and authors
  • Task and session records tied to ongoing work
  • Manual notes and problem statements
  • Compact queryable context for AI assistants
  • Encrypted local storage with repo-scoped keys
  • Enough detail to explain what changed and why it mattered

Team handoff

When one developer starts where another left off

Imagine Iksha built the first half of an affiliate payout feature last week. Today Arjun has to continue the same work. Without good memory, Arjun has to read commits, open several files, and ask the AI agent for help with a prompt that tries to recreate the whole background.

With Memoflow, Arjun can query the repo and quickly see what Iksha already built, what problem she was solving, which files changed, and which risks or follow-up notes were left behind. The handoff becomes smoother because the project still remembers the feature.

What this means in practice: the next developer can understand the old implementation faster, keep the same direction, and avoid losing context that never made it into code comments.

Return to task

When the same developer comes back after a gap

Let’s say Iksha pauses work on login retries because production issues take priority. Two weeks later she comes back. Normally she would need to reopen old tabs, remember what the agent already knew, and explain the entire task again before doing useful work.

Memoflow shortens that ramp-up. Iksha can ask for the relevant context, see the earlier notes, pull up the last captured work, and continue with an AI agent that already has the important background. She spends less time re-explaining and more time moving the task forward.

Why teams like this: it saves repeated context writing, reduces forgotten details, and makes long-running tasks far easier to resume.

Install

Quick start

Add Memoflow to your project, then initialize it so your repo can start collecting useful working memory right away. 

gem "memoflow", "~> 0.1.3"

Then install and initialize it:

bundle install
bundle exec memoflow init
bundle exec memoflow install-hook
bundle exec memoflow task start "Fix webhook retries"
bundle exec memoflow task note "Sentry shows duplicate retries after timeout"
bundle exec memoflow annotate "Investigating retry handling"

Security

Generate a MEMOFLOW_KEY

Memoflow encrypts stored context locally. Every repository should use its own key, so one project’s memory stays separate from another. 

ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'

or:

openssl rand -hex 32

Then export it:

export MEMOFLOW_KEY="paste-generated-key-here"

Why it should be project-specific

  • It isolates one repo's memory from another
  • It limits the blast radius if a key is exposed
  • It keeps team access scoped to the repos they should decrypt

Configuration

Rails initializer

A simple initializer is enough for most Rails apps. The main idea is to connect Memoflow to your project key and choose where memory should live. 

Memoflow.configure do |config|
  config.encryption_key = ENV.fetch("MEMOFLOW_KEY")
  config.storage_policy = :repo
end

If you want external storage, set config.storage_policy = :external and provide a custom storage_path.

Workflow

Recommended workflow

The best results come from treating Memoflow like a lightweight work journal for meaningful tasks. 

bundle exec memoflow task start "Investigate payout mismatch"
bundle exec memoflow task note "Mismatch appears after retry/reconciliation"
bundle exec memoflow annotate "Checking settlement and commission flows"
bundle exec memoflow capture --last
bundle exec memoflow task finish

Memoflow works best when each non-trivial task starts with a task record and each debugging thread gets a short note.

For example, if Iksha is fixing login retries, she can start the task, save a short note about the failing flow, and leave enough breadcrumbs that the next session starts with context instead of confusion.

Integration

AI integration

Memoflow becomes especially useful when an agent needs to understand earlier work without being re-briefed from scratch.

Query stored context directly:

bundle exec memoflow query "payout mismatch"
bundle exec memoflow context "affiliate reconciliation work"

Or expose a local HTTP endpoint for AI tooling:

bundle exec memoflow serve 4599
curl "http://127.0.0.1:4599/query?q=retry"
curl "http://127.0.0.1:4599/context?q=retry"

So if Iksha asks her AI agent to continue the login task, the agent can first retrieve the saved context and respond with better continuity.

Storage

Security and storage

Memoflow is designed to keep sensitive context local and scoped, which is important when project history contains internal reasoning or debugging details.

  • Records are compressed and encrypted with AES-256-GCM
  • Data is stored locally by default under .memoflow
  • The key is never written to disk by Memoflow
  • Export bundles remain encrypted with the same key

Support

Compatibility

Memoflow is currently targeted at Ruby >= 2.3.0. That makes it friendlier to older Rails applications while still supporting modern Ruby environments.

In other words, teams working on legacy Rails projects do not have to give up better memory just because the app is not brand new.