gomem

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 2, 2026 License: MIT Imports: 8 Imported by: 0

README

GoMem — Persistent Memory for AI Coding Agents

A fast, single-binary Go tool for persistent, searchable memory. Designed for AI coding agents (pi, Claude Code, Cline, etc.).

Core principle: Search GoMem FIRST, read files SECOND. GoMem stores concise structural summaries (not raw file contents), saving 70-95% tokens vs re-reading source files. Memory survives context resets and compaction.

Quick Start

# Build
go build -o gomem ./cmd/gomem

# Index your project (stores structural summaries of every file)
gomem save-all

# Search — always do this before read/grep/cat/ls/head
gomem search "authentication"
gomem search "database schema"

# List what's in memory
gomem list

# Store key insights
gomem remember arch-decision "Hexagonal architecture with ports and adapters"

# Delete a memory
gomem delete my-key

# Install skill for your AI agent (auto-creates AGENTS.md too)
gomem skill claude
gomem skill pi

How It Works

GoMem uses Bleve for full-text search with BM25 scoring. Each project gets its own .gomem directory in the project root — fully isolated.

save-all — Project Indexing

gomem save-all walks your project and generates concise structural summaries for every source file:

Instead of reading 500 lines of raw code... ...GoMem stores this
func (s *Store) Search(q string, limit int) ([]SearchHit, uint64, error) { ... 20 lines ... } (s *Store) Search(q string, limit int) ([]SearchHit, uint64, error)

Supported formats: Go, Python, Java, TypeScript, JavaScript, Rust, C/C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, Lua, SQL, Terraform, Dockerfile, Makefile, and 50+ more.

CLI Commands

Command Description
remember <id> <text> Store a memory (summary, key insight, decision)
search <query> Search memories (use * for all)
list List all memories
delete <id> Delete a memory by ID
save-all Index current project as concise summaries
skill <agent> Install skill for an AI agent
help Show help
skill — Install for Any AI Agent

Installs the GoMem skill so the agent knows to use GoMem before filesystem tools. Also creates AGENTS.md at the project root for automatic agent instruction.

gomem skill                   # List all supported agents
gomem skill claude            # Install for Claude Code
gomem skill pi                # Install for Pi
gomem skill cline             # Install for Cline
gomem skill codex             # Install for OpenAI Codex CLI
gomem skill copilot           # Install for GitHub Copilot
gomem skill cursor            # Install for Cursor
gomem skill windsurf          # Install for Windsurf
gomem skill zed               # Install for Zed
gomem skill kilo              # Install for Kilo Code
gomem skill continue          # Install for Continue
gomem skill gemini            # Install for Gemini CLI
gomem skill claude --global   # Install globally in ~/.claude/

AGENTS.md

Every gomem save-all or gomem skill run creates/updates AGENTS.md at the project root. AI coding agents automatically read this file on session start, instructing them to:

1. Search first — Before read, ls, grep, find, cat, head, or memo_search:
   gomem list
   gomem search "<topic>"

2. Filesystem only if needed — Only if GoMem returns nothing useful

3. Store what you learn — gomem remember <id> "<concise summary>"

4. Index new projects — gomem save-all

Performance

Search Latency (Bleve index)
$ go test -bench=BenchmarkSearch -benchtime=30x
BenchmarkSearch-4   30   5.0ms/op   P50: 4.9ms   P95: 5.9ms   P99: 6.0ms

10k entries, ~200 bytes each, 3-word queries on Intel i5-7300HQ (2017 laptop).

Token Savings on Real Repos
Project Language Files Raw chars GoMem chars Saved
GoMem (self) Go 28 96,902 9,293 90%
Chalk JavaScript 35 140,731 2,562 98%
Express JavaScript 214 734,039 16,377 97%
Zod TypeScript 580 5,872,285 92,530 98%

Benchmarks: gomem save-all then sum raw source characters vs stored summary characters.

When to Use GoMem vs Read/Grep/Ls/Cat/Head

Use GoMem when you need to KNOW what's in the codebase

GoMem stores structural summaries — package names, imports, structs, function signatures, doc comments. This covers ~80% of what an agent needs. Real examples from the GoMem project:

Question GoMem query What you get vs reading raw file
"What does the store layer do?" gomem search "Store struct" Package main. Imports: fmt, os, bleve/v2... Structs: Store{}. Functions: NewStore(), Remember(), Search(), Delete(), Close(), DocCount() 4,103 chars → 1,265 (70% saved)
"What functions does saveall.go have?" gomem search "saveall.go" Functions: cmdSaveAllImpl(), summarizeProject(), buildCompactTree(), summarizeFile(), isBinaryExt(), summarizeGoFile(), summarizeMarkdown(), summarizeText()... 20,518 chars → 3,183 (85% saved)
"What imports does the project use?" gomem search "Imports:" fmt, os, bleve/v2, v2/mapping, search/query, path/filepath, regexp, strings, testing, math/rand, time, sort, runtime All 7 source files → one line
"Is there a function called NewStore?" gomem search "NewStore" // NewStore opens an existing Bleve index at path or creates a new one. NewStore(path string) (*Store, error) Must grep + read full function body
"What does this project do?" gomem search "project-overview" Project GoMem: 93 files (7 Go, 9 Markdown, 77 other). Root: ... Read README + scan directory tree
"Find all agent configuration" gomem search "claude" AgentConfig{Name, Dir, InstallFile, Format, Description}. Agents: pi, claude, cline, codex, copilot, cursor, windsurf, zed, kilo, continue, gemini grep across skill.go + match agent names
Use Read/Grep when you need to SEE the exact code

Some tasks genuinely require raw source:

Situation Why you need read
Debugging a specific line Need exact line numbers and surrounding context
Counting occurrences grep -c for exact frequency
Regex pattern matching GoMem doesn't support regex
Verifying a fix Need to see the full function body, not just the signature
The project wasn't indexed No .gomem directory exists yet
How it saves tokens

Compression ratio is the key. A typical function in source code:

// Search performs a full-text query against the index and returns matching hits.
func (s *Store) Search(q string, limit int) ([]SearchHit, uint64, error) {
    if limit <= 0 || limit > 100 {
        limit = 10
    }
    // ... 15+ lines of implementation
}

GoMem stores just the signature + doc comment:

// Search performs a full-text query against the index and returns matching hits.
(s *Store) Search(q string, limit int) ([]SearchHit, uint64, error)

That's 90% fewer characters — and the agent still knows the exact API, parameters, and return types.

The compounding effect

The real savings come from cross-session persistence. You index once with gomem save-all, and that knowledge persists across context resets forever. Every time context compacts:

Approach Tokens per reset After 10 resets Cumulative vs re-reading
Re-read all source files ~559,878 ~5,598,780 —
gomem list + 2 searches ~2,827 ~28,270 99.5% fewer tokens

GoMem memory survives compaction. On the first session you pay the indexing cost (summaries of all files). Every subsequent session you just pay for gomem list + a few searches — a fraction of what re-reading from scratch would cost.

Files

GoMem/
├── main.go         CLI dispatcher and command handlers
├── store.go        Bleve search engine wrapper
├── saveall.go      Project indexing with structural summaries
├── skill.go        Agent skill installer + AGENTS.md writer
├── types.go        Shared types
├── store_test.go   Unit tests
├── bench_test.go   Benchmark
├── skills/         Agent skill files
│   └── gomem/
│       ├── SKILL.md
│       └── scripts/
├── AGENTS.md       Auto-generated agent instructions
└── README.md

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Agents = map[string]AgentConfig{
	"claude":      {Name: "Claude Code", Dir: ".claude/skills/gomem", Format: "skill", Description: "Install for Claude Code (.claude/skills/gomem/)"},
	"claude-code": {Name: "Claude Code", Dir: ".claude/skills/gomem", Format: "skill", Description: "Install for Claude Code (.claude/skills/gomem/)"},
	"pi":          {Name: "Pi", Dir: ".pi/skills/gomem", Format: "skill", Description: "Install for Pi (.pi/skills/gomem/)"},
	"cline":       {Name: "Cline", Dir: ".cline/skills/gomem", Format: "skill", Description: "Install for Cline (.cline/skills/gomem/)"},
	"codex":       {Name: "OpenAI Codex CLI", Dir: ".codex/skills/gomem", Format: "skill", Description: "Install for OpenAI Codex CLI (.codex/skills/gomem/)"},
	"copilot":     {Name: "GitHub Copilot", Dir: ".copilot/skills/gomem", Format: "skill", Description: "Install for GitHub Copilot (.copilot/skills/gomem/)"},
	"cursor":      {Name: "Cursor", Dir: ".cursor/rules/gomem", Format: "skill", Description: "Install for Cursor (.cursor/rules/gomem/)"},
	"windsurf":    {Name: "Windsurf", Dir: ".windsurf/rules/gomem", Format: "skill", Description: "Install for Windsurf (.windsurf/rules/gomem/)"},
	"zed":         {Name: "Zed", Dir: ".zed/skills/gomem", Format: "skill", Description: "Install for Zed (.zed/skills/gomem/)"},
	"kilo":        {Name: "Kilo Code", Dir: ".kilo/skills/gomem", Format: "skill", Description: "Install for Kilo Code (.kilo/skills/gomem/)"},
	"kilo-code":   {Name: "Kilo Code", Dir: ".kilo/skills/gomem", Format: "skill", Description: "Install for Kilo Code (.kilo/skills/gomem/)"},
	"continue":    {Name: "Continue", Dir: ".continue/skills/gomem", Format: "skill", Description: "Install for Continue (.continue/skills/gomem/)"},
	"gemini":      {Name: "Gemini CLI", Dir: ".gemini/skills/gomem", Format: "skill", Description: "Install for Gemini CLI (.gemini/skills/gomem/)"},
	"gemini-cli":  {Name: "Gemini CLI", Dir: ".gemini/skills/gomem", Format: "skill", Description: "Install for Gemini CLI (.gemini/skills/gomem/)"},
}

Agents lists all supported AI coding agents.

Functions

func FindSkillSource 

func FindSkillSource() (string, error)

FindSkillSource finds the skills/gomem directory relative to the binary or cwd.

func SaveAll 

func SaveAll(rootDir string, store *Store) (fileCount int, err error)

SaveAll indexes a project into GoMem with CONCISE summaries of each file. This saves 10x-100x tokens compared to re-reading raw files. It opens or creates a store at rootDir/.gomem, indexes all files, and returns the number of files indexed.

func WriteAgentsMd 

func WriteAgentsMd(projectRoot string)

WriteAgentsMd creates or updates AGENTS.md at the project root so AI coding agents automatically use GoMem before filesystem tools.

Types

type AgentConfig 

type AgentConfig struct {
	Name        string
	Dir         string
	InstallFile string
	Format      string
	Description string
}

AgentConfig describes where and how to install the skill for a specific agent.

type MemoryDoc 

type MemoryDoc struct {
	ID   string `json:"id"`
	Text string `json:"text"`
}

MemoryDoc is the document stored in the Bleve index.

type SearchHit 

type SearchHit struct {
	ID    string  `json:"id"`
	Score float64 `json:"score"`
	Text  string  `json:"text"`
}

SearchHit is a single result from a search.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store wraps a Bleve index for persistent memory storage.

func NewStore 

func NewStore(path string) (*Store, error)

NewStore opens an existing Bleve index at path or creates a new one.

func (*Store) Close 

func (s *Store) Close() error

Close closes the underlying Bleve index, flushing all pending writes.

func (*Store) Delete 

func (s *Store) Delete(id string) error

Delete removes a document from the index by ID. Returns an error if the document doesn't exist.

func (*Store) DocCount 

func (s *Store) DocCount() (uint64, error)

DocCount returns the total number of indexed documents.

func (*Store) Remember 

func (s *Store) Remember(id, text string) error

Remember stores a text entry in the index under the given ID.

func (*Store) Search 

func (s *Store) Search(q string, limit int) ([]SearchHit, uint64, error)

Search performs a full-text query against the index and returns matching hits.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gomem command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.