neocortex.md

Abstract

Every AI agent with persistent memory faces the same question: how should long-term knowledge be structured?

Today, the answer is “however the developer felt like.” Mem0 uses proprietary JSON. MemGPT stores memory blocks. OpenAI's memory is an opaque internal format. Most open-source agents use unstructured markdown files that grow until they become unusable. There is no standard, no interoperability, and no theory behind the design.

The human neocortex solved this problem. It stores long-term knowledge in schema-organized, domain-specialized regions — not as raw recordings, but as compressed, interconnected patterns extracted from experience. Knowledge is modular (cortical columns), associative (everything connects), and continuously refined (reconsolidation on retrieval). The neocortex doesn't hoard — it curates.

neocortex.md proposes a standard format for AI agent long-term memory inspired by neocortical organization. The specification defines: a schema-based section structure mirroring cortical specialization; metadata conventions for tracking memory strength and freshness; consolidation rules governing how memories transform over time; and size constraints grounded in token economics.

The result: a plain-text, human-readable, LLM-parseable memory file that any agent can read, write, and share. A 10,000-token MEMORY.md holding ~200 curated entries can encode what matters about a person, their projects, their preferences, and the lessons an agent has learned — at a marginal cost of $0.003 per interaction.

Table of Contents

1. The Problem: Every Agent Reinvents Memory
2. Biological Foundation
3. Current Approaches and Their Limits
4. Design Principles
5. The neocortex.md Specification
6. Schema Sections
7. Entry Format and Metadata
8. Consolidation Rules
9. Size Constraints and Pruning
10. Handling Contradictions
11. Multi-File Architecture
12. Integration with Agent Brain Architecture
13. Benchmarks
14. What We Don't Yet Know
15. Specification Reference
16. References

1. The Problem: Every Agent Reinvents Memory

Open any AI agent framework. Find where it stores long-term memory. You will discover one of the following:

A JSON blob. Keys like "user_preferences", "conversation_summaries", "facts". No schema. No rules for what goes in or comes out. Grows monotonically until someone manually trims it.

A vector database. Memories embedded as 1536-dimensional vectors, retrieved by cosine similarity. Excellent for fuzzy matching. Terrible for structured recall.

An unstructured markdown file. The honest approach. Dump knowledge as bullet points. Works beautifully for the first 50 entries. By entry 200, it's a haystack.

Nothing at all. Most agents are still amnesic. Every conversation starts from zero. The user repeats their name, preferences, and project context. Every. Single. Time.

The Interoperability Void

An agent built on Mem0 cannot read memories from a MemGPT agent. Switching frameworks means starting over. Memory — the most valuable thing an agent accumulates — is locked in proprietary silos.

What Would a Standard Look Like?

A good memory format needs to be:

1. Plain text — no databases, no binary formats, no infrastructure
2. Human-readable — the user can open and understand their agent's memory
3. LLM-parseable — the model can read and update it without special tools
4. Structured — organized sections, consistent conventions
5. Compact — optimized for token efficiency
6. Self-describing — includes its own schema and version
7. Portable — any agent can read any other agent's memory file

The human brain already has such a format. The neocortex stores knowledge in domain-specialized regions with consistent internal organization. It's been refined over 200 million years of mammalian evolution.

2. Biological Foundation

2.1 The Neocortex as Long-Term Store

The neocortex is the brain's warehouse for stable, consolidated knowledge. Unlike the hippocampus — which rapidly encodes new experiences as raw episodes — the neocortex stores extracted patterns, schemas, and generalized knowledge derived from experience.

Key properties:

• Slow learning rate. Acquires knowledge gradually through repeated exposure, avoiding catastrophic interference (McClelland et al. 1995).
• Distributed representations. Memories stored across overlapping neural populations — graceful degradation, not brittle failure.
• Modular organization. ~150,000 cortical columns (Mountcastle 1957, Hawkins 2021), each specialized through connectivity.
• Associative architecture. Content-addressable. Partial cues trigger full pattern completion.

2.2 Schema Theory

Frederic Bartlett (1932) introduced schemas — “active knowledge structures” that organize memory reconstructively. Tse et al. (2007) demonstrated that pre-existing spatial schemas consolidated new memories into the neocortex in just 48 hours instead of weeks.

van Kesteren et al. (2012) proposed the SLIMM framework, showing the mPFC routes new information based on schema fit:

2.3 Transformation, Not Copying

Trace Transformation Theory (Winocur & Moscovitch 2011): Memories don't just move from short-term to long-term storage. They change form:

• Recent: Detailed, episodic, high-fidelity. “At 3pm yesterday, Sarah said the deploy broke because the env var was missing.”
• Consolidated: Compressed, semantic, gist-extracted. “Deploy requires DATABASE_URL env var.”
• Deeply integrated: Schema-merged, maximum compression. Part of the “deployment checklist” mental model.

2.4 Cortical Columns: The Case for Modularity

Vernon Mountcastle discovered the cortical column — the fundamental computational unit of the neocortex. Jeff Hawkins' Thousand Brains Theory proposes each of ~150,000 columns builds its own predictive model.

The brain doesn't use one giant memory store. It uses thousands of semi-independent modules that cross-reference each other. This suggests agent memory should be modular with cross-referencing.

2.5 Forgetting Is a Feature

The brain actively prunes ~50% of synaptic connections between age 2 and adulthood. This correlates with improved cognitive function. Selective forgetting reduces interference, improves generalization, saves token budget, and keeps knowledge current.

3. Current Approaches and Their Limits

3.1 Vector Databases

Vector databases (Pinecone, Qdrant, Weaviate, Chroma) store memories as high-dimensional embeddings. Good at: fuzzy matching, scale. Bad at: structured relationships, updates, contradiction detection, and they require infrastructure.

3.2 Mem0

Mem0 (41k+ GitHub stars, $24M funding) achieves 26% higher accuracy than OpenAI Memory on LOCOMO. The tradeoff: Memory is high-quality but opaque and locked in a hosted service with proprietary format.

3.3 MemGPT / Letta

OS-inspired memory hierarchy — core memory as “RAM,” archival as “disk.” Clever architecture for managing memory, but not a standard for formatting it. JSON structures specific to Letta.

3.4 Plain Markdown

The right foundation: human-readable ✓, LLM-parseable ✓, no infrastructure ✓, portable ✓. But without conventions, each agent's MEMORY.md evolves differently. No guidance on structure, metadata, consolidation, or size constraints.

4. Design Principles

Twelve design principles derived from neocortical organization:

Spotlight: Two-Speed Learning (CLS)

The hippocampus learns fast but forgets fast — it captures today's events. The neocortex learns slowly but retains permanently. If the neocortex learned at the hippocampus's speed, new knowledge would overwrite existing knowledge (catastrophic interference).

For AI agents: Fast buffer = daily logs. Slow store = MEMORY.md. Consolidation = defrag.md process that transfers important patterns.

Spotlight: Gist Over Verbatim

For MEMORY.md entries:

On January 15th at 3:47pm, during a Slack conversation in #engineering,
Sarah mentioned that the new API endpoint /api/v2/users requires OAuth2
Bearer tokens and she suggested we use PKCE flow because our app is a
single-page application.

API v2 uses OAuth2 + PKCE (SPA requirement). Sarah confirmed Jan 15.

Both carry the same actionable knowledge. Scale the savings across 200 entries: 8,600 tokens saved — enough for 80 more memories.

5. The neocortex.md Specification

5.1 File Header

<!-- neocortex.md v1.0 -->
<!-- agent: atlas -->
<!-- owner: Jane Chen -->
<!-- consolidated: 2026-01-31 -->
<!-- entries: 187 | tokens: ~9,400 -->

The header makes the file self-describing. Any agent reading a foreign MEMORY.md can immediately identify the format, version, and size.

5.2 Document Title

Single # Memory heading. Convention, not requirement — consistency aids interoperability.

5.3 Filename Convention

5.4 Section Structure

## Identity
## People
## Projects
## Knowledge
## Patterns
## Lessons
## Context

Sections ordered by stability — Identity changes least, Context changes most. Agents may add custom sections but should not exceed 10 total.

6. Schema Sections

## Identity
- Name: Atlas | Role: Personal AI assistant
- Owner: Jane Chen | Timezone: PST | Languages: English, Mandarin
- Style: Direct, resourceful, occasionally sarcastic
- Values: Competence over politeness, actions over promises

## People
- Roman: Owner. Seattle. GitHub @janechen. Prefers direct communication.
  Runs multiple projects. Named the agent Atlas.
- Sarah (CTO, Project Alpha): Technical, detail-oriented. Prefers async.

## Projects
- Acme API: AI agent platform. 20+ users. Next.js + Postgres + Redis.
  Key decision: Always use connection pooling for Postgres.
- Mobile App: React Native client. In beta testing.

## Knowledge
- Vercel deploys require git commits from jane@example.com
- Railway CLI: `railway link` then `railway up` for deploys
- OAuth2 + PKCE for SPA authentication (never implicit grant)

## Patterns
- Roman prefers dark theme, JetBrains Mono + Inter fonts
- Responds faster to Telegram than email
- Late night (23:00-02:00): often working, open to interruptions

## Lessons
- ALWAYS write important things to files, not "mental notes"
- Telegram config uses `botToken`, not `token` — cost 2 hours
- Never send half-baked replies to messaging surfaces

## Context
- Current focus: Documentation sprint (Jan-Feb 2026)
- Acme API: monitoring for new user signups
- Waiting for: hardware delivery for Atlas pendant project

7. Entry Format and Metadata

7.1 Entry Format

Formatting rules:

1. One concept per entry
2. Start with the subject for scannability
3. Periods or semicolons to separate sub-facts
4. Keep entries under 100 tokens
5. Multi-line: 2-space indent for continuation

Target: 50 tokens per entry average. This produces ~200 entries in a 10,000-token budget.

7.2 Metadata

- API rate limit: 100 req/min per key. Use exponential backoff on 429s.
  <!-- nx: u=2026-01-15 c=high a=7 -->

The nx: prefix identifies neocortex.md metadata. Add metadata to Knowledge, Lessons, and Projects where it aids pruning. Skip for Identity and Patterns.

8. Consolidation Rules

8.1 The Pipeline

Daily logs          →  Extraction    →  Integration     →  MEMORY.md
(hippocampal buffer)   (identify       (update entries,    (neocortical store)
                       significant     add new ones,
                       items)          prune stale)

8.2 Frequency

8.3 The Transformation Rule

Entries transform over time:

- Sarah confirmed API v2 uses OAuth2+PKCE (Slack #engineering, Jan 15).
  Migration deadline: Feb 1. She'll review our implementation.
  <!-- nx: u=2026-01-15 c=high a=1 s=user -->

- API v2: OAuth2+PKCE. Migration by Feb 1. Sarah reviewing.
  <!-- nx: u=2026-01-15 c=high a=4 -->

- API v2 uses OAuth2+PKCE.
  <!-- nx: u=2026-01-15 c=high a=11 -->

9. Size Constraints and Pruning

9.1 Token Budget

9.2 Entry Limits by Section

9.3 Pruning Algorithm

for each entry:
    score = compute_retention_score(entry)
    if score < PRUNE_THRESHOLD:
        if entry.age > 90 days:
            archive(entry)  # move to memory/archive/
        elif entry.age > 30 days:
            compress(entry)  # reduce to gist
        else:
            flag_for_review(entry)

Never auto-prune: Identity entries, user-marked entries, entries with access count >10, and Lessons.

10. Handling Contradictions

- ~~PostgreSQL for all projects~~ → Split: PostgreSQL for web, SQLite for CLI (2026-01-20)
  <!-- nx: u=2026-01-20 c=high x="PostgreSQL for all projects" -->

11. Multi-File Architecture

MEMORY.md                  ← Core file (always loaded, ~5–10K tokens)
├── Identity
├── People
├── Lessons
├── Context
└── Pointers to satellites

memory/
├── projects/
│   ├── alpha.md           ← Project-specific knowledge
│   └── beta.md
├── knowledge/
│   ├── apis.md            ← Domain-specific technical knowledge
│   └── infrastructure.md
├── archive/
│   └── 2025.md            ← Archived entries, compressed
└── YYYY-MM-DD.md          ← Daily logs (hippocampal buffer)

Stay single-file when: under 10K tokens, all sections frequently needed together. Split when: exceeds 15K tokens, some sections rarely co-accessed, multiple agents share partial memory.

12. Integration with Agent Brain Architecture

New experience
    ↓
Daily log (memory/YYYY-MM-DD.md)    ← hippocampal buffer
    ↓ [defrag.md consolidation]
HIPPOCAMPUS.md updated              ← index entry created
    ↓
MEMORY.md updated                    ← knowledge stored (neocortex.md format)
    ↓ [synapse.md sharing]
Other agents receive knowledge       ← inter-agent transfer

Implementation Status (January 31, 2026)

Without the Full Suite

neocortex.md works standalone. Minimum viable implementation:

1. Structure MEMORY.md with the seven standard sections
2. Follow the entry format guidelines
3. Manually consolidate during natural pauses
4. Prune when the file grows beyond 10K tokens

No infrastructure, no dependencies, no external services. A text editor and a convention.

13. Benchmarks

All measurements from a production agent (Atlas) running on real workloads over 30 days.

13.1 Storage Efficiency

13.2 Retrieval Quality

13.3 Consolidation Costs

Compare to vector database approaches: Pinecone starts at $50/month. neocortex.md costs 50–150× less.

13.4 First Live Migration (Atlas, January 31 2026)

The first production migration — a real migration on a real agent with real data.

Token count increased ~28% due to metadata and structure. But information density improved — previously ambiguous entries are now explicitly categorized. The metadata overhead pays for itself at the first consolidation cycle.

14. What We Don't Yet Know

15. Specification Reference

<!-- neocortex.md v1.0 -->
<!-- agent: {agent_id} -->
<!-- consolidated: {YYYY-MM-DD} -->
<!-- entries: {count} | tokens: ~{estimate} -->

# Memory

## Identity
- Name: {agent_name} | Role: {role}
- Owner: {owner_name} | Timezone: {tz}
- Style: {communication style}

## People
- {Person}: {role}. {key facts}. {communication preferences}.

## Projects
- {Project}: {status}. {key architecture}. {current blocker/next step}.

## Knowledge
- {Fact}: {compressed knowledge}.
  <!-- nx: u={date} c={confidence} -->

## Patterns
- {Pattern}: {observed behavior or preference}.

## Lessons
- {Lesson}: {what happened} → {what to do instead}.

## Context
- {Current situation}: {time-sensitive detail}.

---
<!-- Consolidation rules:
  - Max entries: 300
  - Max tokens: 15,000
  - Prune: accessed=0 AND age>90d
  - Compress: accessed<3 AND age>30d
  - Archive: moved to memory/archive/
  - Frequency: daily (light), weekly (deep), monthly (full)
-->

16. References

Neuroscience

1. Bartlett, F.C. (1932). Remembering. Cambridge University Press.
2. McClelland, J.L. et al. (1995). Complementary learning systems. Psychological Review, 102(3).
3. Mountcastle, V.B. (1957, 1997). The columnar organization of the neocortex. Brain, 120(4).
4. Tse, D. et al. (2007). Schemas and memory consolidation. Science, 316(5821).
5. Winocur, G. & Moscovitch, M. (2011). Memory transformation and systems consolidation. JINS, 17(5).
6. van Kesteren, M.T.R. et al. (2012). How schema and novelty augment memory formation. Trends Neurosci., 35(4).
7. Hawkins, J. (2021). A Thousand Brains. Basic Books.
8. Tononi, G. & Cirelli, C. (2006). Sleep function and synaptic homeostasis. Sleep Med Rev, 10(1).
9. Brainerd, C.J. & Reyna, V.F. (2002). Fuzzy-trace theory. Current Directions in Psych Sci, 11(5).
10. Ebbinghaus, H. (1885). Über das Gedächtnis. Leipzig.
11. Nader, K. et al. (2000). Fear memories require protein synthesis for reconsolidation. Nature, 406.
12. Kumaran, D. et al. (2016). What learning systems do intelligent agents need? Trends Cog Sci, 20(7).

AI Memory Systems

13. Mem0: Building Production-Ready AI Agent Memory. arXiv:2504.19413 (2025).
14. MemGPT/Letta. Packer et al., UC Berkeley (2023).
15. MemoryOS. EMNLP 2025.
16. KARMA: Knowledge-based Agent with Reference frames for Memory. arXiv:2409.14908 (2024).
17. LLMLingua-2. Microsoft Research (2024). Prompt compression.

Knowledge Management

18. Luhmann, N. Zettelkasten method. ~90,000 cards → 70 books.
19. Ahrens, S. (2017). How to Take Smart Notes.